Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,31 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+docs/assets/demo1-task-execution.gif filter=lfs diff=lfs merge=lfs -text
+docs/assets/demo2-claude-skill.gif filter=lfs diff=lfs merge=lfs -text
+docs/assets/demo3-web-search.gif filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/ArsenalSC-Regular.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/CrimsonPro-Bold.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/CrimsonPro-Italic.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/CrimsonPro-Regular.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/IBMPlexMono-Bold.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/IBMPlexMono-Regular.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/IBMPlexSerif-Bold.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/IBMPlexSerif-BoldItalic.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/IBMPlexSerif-Italic.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/IBMPlexSerif-Regular.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/JetBrainsMono-Bold.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/JetBrainsMono-Regular.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/Jura-Light.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/Jura-Medium.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/LibreBaskerville-Regular.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/Lora-Bold.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/Lora-BoldItalic.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/Lora-Italic.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/Lora-Regular.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/WorkSans-Bold.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/WorkSans-BoldItalic.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/WorkSans-Italic.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/WorkSans-Regular.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/canvas-design/canvas-fonts/YoungSerif-Regular.ttf filter=lfs diff=lfs merge=lfs -text
+mini_agent/skills/theme-factory/theme-showcase.pdf filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,62 @@
+# Python
+__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
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Workspace
+workspace/
+*.log
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Config (contains API keys)
+config.yaml
+mcp.json
+
+# test file
+demo.py
+hello.py
+test.txt
+hello_world.py
+demo_test.txt
+demo_commands.txt
+mcp.json.bak
+
+docs/assets/backup/
+docs/assets/preview.html
+
+claude.md
+
+.agent_memory.json

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "mini_agent/skills"]
+	path = mini_agent/skills
+	url = https://github.com/anthropics/skills.git

CODE_OF_CONDUCT.md

@@ -0,0 +1,45 @@
+# Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when an individual is representing the project or its community in public spaces. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

CODE_OF_CONDUCT_CN.md

@@ -0,0 +1,48 @@
+# 行为准则
+
+## 我们的承诺
+
+为了营造开放和友好的环境，我们作为贡献者和维护者承诺：无论年龄、体型、残疾、种族、性别认同和表达、经验水平、教育程度、社会经济地位、国籍、外貌、种族、宗教或性取向如何，参与我们的项目和社区的每个人都不会受到骚扰。
+
+## 我们的标准
+
+有助于创建积极环境的行为包括：
+
+- 使用友好和包容的语言
+- 尊重不同的观点和经验
+- 优雅地接受建设性批评
+- 专注于对社区最有利的事情
+- 对其他社区成员表示同理心
+
+不可接受的行为包括：
+
+- 使用性暗示的语言或图像，以及不受欢迎的性关注或挑逗
+- 发表侮辱性/贬损性评论，进行人身攻击或政治攻击
+- 公开或私下骚扰
+- 未经明确许可，发布他人的私人信息（如地址、电子邮件地址）
+- 在专业环境中可被合理认为不适当的其他行为
+
+## 我们的责任
+
+项目维护者有责任澄清可接受行为的标准，并应对任何不可接受的行为采取适当和公平的纠正措施。
+
+项目维护者有权利和责任删除、编辑或拒绝不符合本行为准则的评论、提交、代码、wiki 编辑、问题和其他贡献，或暂时或永久禁止任何他们认为有不适当、威胁、冒犯或有害行为的贡献者。
+
+## 范围
+
+本行为准则适用于项目空间和公共空间，当个人代表项目或其社区时。代表项目或社区的示例包括：使用官方项目电子邮件地址、通过官方社交媒体账户发帖，或在在线或离线活动中担任指定代表。项目维护者可以进一步定义和阐明项目的代表性。
+
+## 执行
+
+可以通过联系项目团队来报告滥用、骚扰或其他不可接受的行为。所有投诉都将被审查和调查，并将做出被认为必要和适当的回应。项目团队有义务对事件报告者保密。具体执行政策的更多细节可能会单独发布。
+
+不善意遵守或执行行为准则的项目维护者可能会面临项目领导层其他成员决定的临时或永久性后果。
+
+## 归属
+
+本行为准则改编自 [Contributor Covenant](https://www.contributor-covenant.org/) 2.0 版本，可在 https://www.contributor-covenant.org/version/2/0/code_of_conduct.html 获取。
+
+社区影响指南受到 [Mozilla 的行为准则执行阶梯](https://github.com/mozilla/diversity)的启发。
+
+有关本行为准则的常见问题的答案，请参阅 https://www.contributor-covenant.org/faq。翻译版本可在 https://www.contributor-covenant.org/translations 获取。
+

CONTRIBUTING.md

@@ -0,0 +1,200 @@
+# Contributing Guide
+
+Thank you for your interest in the Mini Agent project! We welcome contributions of all forms.
+
+## How to Contribute
+
+### Reporting Bugs
+
+If you find a bug, please create an Issue and include the following information:
+
+- **Problem Description**: A clear description of the problem.
+- **Steps to Reproduce**: Detailed steps to reproduce the issue.
+- **Expected Behavior**: What you expected to happen.
+- **Actual Behavior**: What actually happened.
+- **Environment Information**:
+  - Python version
+  - Operating system
+  - Versions of relevant dependencies
+
+### Suggesting New Features
+
+If you have an idea for a new feature, please create an Issue first to discuss it:
+
+- Describe the purpose and value of the feature.
+- Explain the intended use case.
+- Provide a design proposal if possible.
+
+### Submitting Code
+
+#### Getting Started
+
+1. Fork this repository.
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/MiniMax-AI/Mini-Agent mini-agent
+   cd mini-agent
+   ```
+
+3. Create a new branch:
+   ```bash
+   git checkout -b feature/your-feature-name
+   # or
+   git checkout -b fix/your-bug-fix
+   ```
+
+4. Install development dependencies:
+   ```bash
+   uv sync
+   ```
+
+#### Development Process
+
+1. **Write Code**
+   - Follow the project's code style (see the [Development Guide](docs/DEVELOPMENT.md#code-style-guide)).
+   - Add necessary comments and docstrings.
+   - Keep your code clean and concise.
+
+2. **Add Tests**
+   - Add test cases for new features.
+   - Ensure all tests pass:
+     ```bash
+     pytest tests/ -v
+     ```
+
+3. **Update Documentation**
+   - If you add a new feature, update the README or relevant documentation.
+   - Keep documentation in sync with your code.
+
+4. **Commit Changes**
+   - Use clear commit messages:
+     ```bash
+     git commit -m "feat(tools): Add new file search tool"
+     # or
+     git commit -m "fix(agent): Fix error handling for tool calls"
+     ```
+   
+   - Commit message format:
+     - `feat`: A new feature
+     - `fix`: A bug fix
+     - `docs`: Documentation updates
+     - `style`: Code style adjustments
+     - `refactor`: Code refactoring
+     - `test`: Test-related changes
+     - `chore`: Build or auxiliary tools
+
+5. **Push to Your Fork**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+6. **Create a Pull Request**
+   - Create a Pull Request on GitHub.
+   - Clearly describe your changes.
+   - Reference any related Issues if applicable.
+
+#### Pull Request Checklist
+
+Before submitting a PR, please ensure:
+
+- [ ] The code follows the project's style guide.
+- [ ] All tests pass.
+- [ ] Necessary tests have been added.
+- [ ] Relevant documentation has been updated.
+- [ ] The commit message is clear and concise.
+- [ ] There are no unrelated changes.
+
+### Code Review
+
+All Pull Requests will be reviewed:
+
+- We will review your code as soon as possible.
+- We may request some changes.
+- Please be patient and responsive to feedback.
+- Once approved, your PR will be merged into the main branch.
+
+## Code Style Guide
+
+### Python Code Style
+
+Follow PEP 8 and the Google Python Style Guide:
+
+```python
+# Good example ✅
+class MyClass:
+    """A brief description of the class.
+    
+    A more detailed description...
+    """
+    
+    def my_method(self, param1: str, param2: int = 10) -> str:
+        """A brief description of the method.
+        
+        Args:
+            param1: Description of parameter 1.
+            param2: Description of parameter 2.
+        
+        Returns:
+            Description of the return value.
+        """
+        pass
+
+# Bad example ❌
+class myclass:  # Class names should be PascalCase
+    def MyMethod(self,param1,param2=10):  # Method names should be snake_case
+        pass  # Missing docstring
+```
+
+### Type Hinting
+
+Use Python type hints:
+
+```python
+from typing import List, Dict, Optional, Any
+
+async def process_messages(
+    messages: List[Dict[str, Any]],
+    max_tokens: Optional[int] = None
+) -> str:
+    """Process a list of messages."""
+    pass
+```
+
+### Testing
+
+- Write tests for new features.
+- Keep tests simple and clear.
+- Ensure tests cover critical paths.
+
+```python
+import pytest
+from mini_agent.tools.my_tool import MyTool
+
+@pytest.mark.asyncio
+async def test_my_tool():
+    """Test the custom tool."""
+    tool = MyTool()
+    result = await tool.execute(param="test")
+    assert result.success
+    assert "expected" in result.content
+```
+
+## Community Guidelines
+
+Please follow our [Code of Conduct](CODE_OF_CONDUCT.md) and be friendly and respectful.
+
+## Questions and Help
+
+If you have any questions:
+
+- Check the [README](README.md) and [documentation](docs/).
+- Search existing Issues.
+- Create a new Issue to ask a question.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).
+
+---
+
+Thank you again for your contribution! 🎉

CONTRIBUTING_CN.md

@@ -0,0 +1,201 @@
+# 贡献指南
+
+感谢你对 Mini Agent 项目的兴趣！我们欢迎各种形式的贡献。
+
+## 如何贡献
+
+### 报告 Bug
+
+如果你发现了 bug，请创建一个 Issue 并包含以下信息：
+
+- **问题描述**：清晰描述问题
+- **复现步骤**：详细的复现步骤
+- **预期行为**：你期望发生什么
+- **实际行为**：实际发生了什么
+- **环境信息**：
+  - Python 版本
+  - 操作系统
+  - 相关依赖版本
+
+### 提出新功能
+
+如果你有新功能的想法，请先创建一个 Issue 讨论：
+
+- 描述功能的用途和价值
+- 说明预期的使用场景
+- 如果可能，提供设计思路
+
+### 提交代码
+
+#### 准备工作
+
+1. Fork 本仓库
+2. 克隆你的 fork：
+   ```bash
+   git clone https://github.com/MiniMax-AI/Mini-Agent mini-agent
+   cd mini-agent
+   ```
+
+3. 创建新分支：
+   ```bash
+   git checkout -b feature/your-feature-name
+   # 或
+   git checkout -b fix/your-bug-fix
+   ```
+
+4. 安装开发依赖：
+   ```bash
+   uv sync
+   ```
+
+#### 开发流程
+
+1. **编写代码**
+   - 遵循项目的代码风格（参考 [开发指南](docs/DEVELOPMENT.md#代码规范)）
+   - 添加必要的注释和文档字符串
+   - 保持代码简洁清晰
+
+2. **添加测试**
+   - 为新功能添加测试用例
+   - 确保所有测试通过：
+     ```bash
+     pytest tests/ -v
+     ```
+
+3. **更新文档**
+   - 如果添加了新功能，更新 README 或相关文档
+   - 保持文档与代码同步
+
+4. **提交更改**
+   - 使用清晰的提交消息：
+     ```bash
+     git commit -m "feat(tools): 添加新的文件搜索工具"
+     # 或
+     git commit -m "fix(agent): 修复工具调用错误处理"
+     ```
+   
+   - 提交消息格式：
+     - `feat`: 新功能
+     - `fix`: Bug 修复
+     - `docs`: 文档更新
+     - `style`: 代码格式调整
+     - `refactor`: 代码重构
+     - `test`: 测试相关
+     - `chore`: 构建或辅助工具
+
+5. **推送到你的 fork**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+6. **创建 Pull Request**
+   - 在 GitHub 上创建 Pull Request
+   - 清楚描述你的更改
+   - 引用相关的 Issue（如果有）
+
+#### Pull Request 检查清单
+
+在提交 PR 之前，请确保：
+
+- [ ] 代码遵循项目规范
+- [ ] 所有测试通过
+- [ ] 添加了必要的测试
+- [ ] 更新了相关文档
+- [ ] 提交消息清晰明确
+- [ ] 没有不相关的更改
+
+### 代码审查
+
+所有 Pull Request 需要经过代码审查：
+
+- 我们会尽快审查你的代码
+- 可能会要求一些修改
+- 请保持耐心并及时响应反馈
+- 审查通过后会被合并到主分支
+
+## 代码规范
+
+### Python 代码风格
+
+遵循 PEP 8 和 Google Python Style Guide：
+
+```python
+# 好的示例 ✅
+class MyClass:
+    """类的简短描述。
+    
+    详细描述...
+    """
+    
+    def my_method(self, param1: str, param2: int = 10) -> str:
+        """方法的简短描述。
+        
+        Args:
+            param1: 参数1的描述
+            param2: 参数2的描述
+        
+        Returns:
+            返回值的描述
+        """
+        pass
+
+# 不好的示例 ❌
+class myclass:  # 类名应该用 PascalCase
+    def MyMethod(self,param1,param2=10):  # 方法名应该用 snake_case
+        pass  # 缺少 docstring
+```
+
+### 类型注解
+
+使用 Python 类型注解：
+
+```python
+from typing import List, Dict, Optional
+
+async def process_messages(
+    messages: List[Dict[str, Any]],
+    max_tokens: Optional[int] = None
+) -> str:
+    """处理消息列表"""
+    pass
+```
+
+### 测试
+
+- 为新功能编写测试
+- 保持测试简单清晰
+- 测试覆盖关键路径
+
+```python
+import pytest
+from mini_agent.tools.my_tool import MyTool
+
+@pytest.mark.asyncio
+async def test_my_tool():
+    """测试自定义工具"""
+    tool = MyTool()
+    result = await tool.execute(param="test")
+    assert result.success
+    assert "expected" in result.content
+```
+
+## 社区准则
+
+请遵守我们的[行为准则](CODE_OF_CONDUCT.md)，保持友好和尊重。
+
+## 问题和帮助
+
+如果有任何问题：
+
+- 查看 [README](README.md) 和 [文档](docs/)
+- 搜索现有的 Issues
+- 创建新的 Issue 提问
+
+## 许可证
+
+提交代码即表示你同意将代码以 [MIT License](LICENSE) 发布。
+
+---
+
+再次感谢你的贡献！ 🎉
+

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 MiniMax
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

MANIFEST.in

@@ -0,0 +1,5 @@
+recursive-include mini_agent/skills *
+include mini_agent/skills/README.md
+include mini_agent/skills/THIRD_PARTY_NOTICES.md
+include mini_agent/skills/agent_skills_spec.md
+

README.md

@@ -0,0 +1,344 @@
+# Mini Agent
+
+English | [中文](./README_CN.md)
+
+**Mini Agent** is a minimal yet professional demo project that showcases the best practices for building agents with the MiniMax M2.1 model. Leveraging an Anthropic-compatible API, it fully supports interleaved thinking to unlock M2's powerful reasoning capabilities for long, complex tasks.
+
+This project comes packed with features designed for a robust and intelligent agent development experience:
+
+*   ✅ **Full Agent Execution Loop**: A complete and reliable foundation with a basic toolset for file system and shell operations.
+*   ✅ **Persistent Memory**: An active **Session Note Tool** ensures the agent retains key information across multiple sessions.
+*   ✅ **Intelligent Context Management**: Automatically summarizes conversation history to handle contexts up to a configurable token limit, enabling infinitely long tasks.
+*   ✅ **Claude Skills Integration**: Comes with 15 professional skills for documents, design, testing, and development.
+*   ✅ **MCP Tool Integration**: Natively supports MCP for tools like knowledge graph access and web search.
+*   ✅ **Comprehensive Logging**: Detailed logs for every request, response, and tool execution for easy debugging.
+*   ✅ **Clean & Simple Design**: A beautiful CLI and a codebase that is easy to understand, making it the perfect starting point for building advanced agents.
+
+## Table of Contents
+
+- [Mini Agent](#mini-agent)
+  - [Table of Contents](#table-of-contents)
+  - [Quick Start](#quick-start)
+    - [1. Get API Key](#1-get-api-key)
+    - [2. Choose Your Usage Mode](#2-choose-your-usage-mode)
+      - [🚀 Quick Start Mode (Recommended for Beginners)](#-quick-start-mode-recommended-for-beginners)
+      - [🔧 Development Mode](#-development-mode)
+  - [ACP \& Zed Editor Integration(optional)](#acp--zed-editor-integrationoptional)
+  - [Usage Examples](#usage-examples)
+    - [Task Execution](#task-execution)
+    - [Using a Claude Skill (e.g., PDF Generation)](#using-a-claude-skill-eg-pdf-generation)
+    - [Web Search \& Summarization (MCP Tool)](#web-search--summarization-mcp-tool)
+  - [Testing](#testing)
+    - [Quick Run](#quick-run)
+    - [Test Coverage](#test-coverage)
+  - [Troubleshooting](#troubleshooting)
+    - [SSL Certificate Error](#ssl-certificate-error)
+    - [Module Not Found Error](#module-not-found-error)
+  - [Related Documentation](#related-documentation)
+  - [Community](#community)
+  - [Contributing](#contributing)
+  - [License](#license)
+  - [References](#references)
+
+## Quick Start
+
+### 1. Get API Key
+
+MiniMax provides both global and China platforms. Choose based on your network environment:
+
+| Version    | Platform                                                       | API Base                   |
+| ---------- | -------------------------------------------------------------- | -------------------------- |
+| **Global** | [https://platform.minimax.io](https://platform.minimax.io)     | `https://api.minimax.io`   |
+| **China**  | [https://platform.minimaxi.com](https://platform.minimaxi.com) | `https://api.minimaxi.com` |
+
+**Steps to get API Key:**
+1. Visit the corresponding platform to register and login
+2. Go to **Account Management > API Keys**
+3. Click **"Create New Key"**
+4. Copy and save it securely (key is only shown once)
+
+> 💡 **Tip**: Remember the API Base address corresponding to your chosen platform, you'll need it for configuration
+
+### 2. Choose Your Usage Mode
+
+**Prerequisites: Install uv**
+
+Both usage modes require uv. If you don't have it installed:
+
+```bash
+# macOS/Linux/WSL
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows (PowerShell)
+python -m pip install --user pipx
+python -m pipx ensurepath
+# Restart PowerShell after installation
+
+# After installation, restart your terminal or run:
+source ~/.bashrc  # or ~/.zshrc (macOS/Linux)
+```
+
+We offer two usage modes - choose based on your needs:
+
+#### 🚀 Quick Start Mode (Recommended for Beginners)
+
+Perfect for users who want to quickly try Mini Agent without cloning the repository or modifying code.
+
+**Installation:**
+
+```bash
+# 1. Install directly from GitHub
+uv tool install git+https://github.com/MiniMax-AI/Mini-Agent.git
+
+# 2. Run setup script (automatically creates config files)
+# macOS/Linux:
+curl -fsSL https://raw.githubusercontent.com/MiniMax-AI/Mini-Agent/main/scripts/setup-config.sh | bash
+
+# Windows (PowerShell):
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/MiniMax-AI/Mini-Agent/main/scripts/setup-config.ps1" -OutFile "$env:TEMP\setup-config.ps1"
+powershell -ExecutionPolicy Bypass -File "$env:TEMP\setup-config.ps1"
+```
+
+> 💡 **Tip**: If you want to develop locally or modify code, use "Development Mode" below
+
+**Configuration:**
+
+The setup script creates config files in `~/.mini-agent/config/`. Edit the config file:
+
+```bash
+# Edit config file
+nano ~/.mini-agent/config/config.yaml
+```
+
+Fill in your API Key and corresponding API Base:
+
+```yaml
+api_key: "YOUR_API_KEY_HERE"          # API Key from step 1
+api_base: "https://api.minimax.io"  # Global
+# api_base: "https://api.minimaxi.com"  # China
+model: "MiniMax-M2.1"
+```
+
+**Start Using:**
+
+```bash
+mini-agent                                    # Use current directory as workspace
+mini-agent --workspace /path/to/your/project  # Specify workspace directory
+mini-agent --version                          # Check version
+
+# Management commands
+uv tool upgrade mini-agent                    # Upgrade to latest version
+uv tool uninstall mini-agent                  # Uninstall if needed
+uv tool list                                  # View all installed tools
+```
+
+#### 🔧 Development Mode
+
+For developers who need to modify code, add features, or debug.
+
+**Installation & Configuration:**
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/MiniMax-AI/Mini-Agent.git
+cd Mini-Agent
+
+# 2. Install uv (if you haven't)
+# macOS/Linux:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+# Windows (PowerShell):
+irm https://astral.sh/uv/install.ps1 | iex
+# Restart terminal after installation
+
+# 3. Sync dependencies
+uv sync
+
+# Alternative: Install dependencies manually (if not using uv)
+# pip install -r requirements.txt
+# Or install required packages:
+# pip install tiktoken pyyaml httpx pydantic requests prompt-toolkit mcp
+
+# 4. Initialize Claude Skills (Optional)
+git submodule update --init --recursive
+
+# 5. Copy config template
+```
+
+**macOS/Linux:**
+```bash
+cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml
+```
+
+**Windows:**
+```powershell
+Copy-Item mini_agent\config\config-example.yaml mini_agent\config\config.yaml
+
+# 6. Edit config file
+vim mini_agent/config/config.yaml  # Or use your preferred editor
+```
+
+Fill in your API Key and corresponding API Base:
+
+```yaml
+api_key: "YOUR_API_KEY_HERE"          # API Key from step 1
+api_base: "https://api.minimax.io"  # Global
+# api_base: "https://api.minimaxi.com"  # China
+model: "MiniMax-M2.1"
+max_steps: 100
+workspace_dir: "./workspace"
+```
+
+> 📖 Full configuration guide: See [config-example.yaml](mini_agent/config/config-example.yaml)
+
+**Run Methods:**
+
+Choose your preferred run method:
+
+```bash
+# Method 1: Run as module directly (good for debugging)
+uv run python -m mini_agent.cli
+
+# Method 2: Install in editable mode (recommended)
+uv tool install -e .
+# After installation, run from anywhere and code changes take effect immediately
+mini-agent
+mini-agent --workspace /path/to/your/project
+```
+
+> 📖 For more development guidance, see [Development Guide](docs/DEVELOPMENT_GUIDE.md)
+
+> 📖 For more production deployment guidance, see [Production Guide](docs/PRODUCTION_GUIDE.md)
+
+## ACP & Zed Editor Integration(optional)
+
+Mini Agent supports the [Agent Communication Protocol (ACP)](https://github.com/modelcontextprotocol/protocol) for integration with code editors like Zed.
+
+**Setup in Zed Editor:**
+
+1. Install Mini Agent in development mode or as a tool
+2. Add to your Zed `settings.json`:
+
+```json
+{
+  "agent_servers": {
+    "mini-agent": {
+      "command": "/path/to/mini-agent-acp"
+    }
+  }
+}
+```
+
+The command path should be:
+- If installed via `uv tool install`: Use the output of `which mini-agent-acp`
+- If in development mode: `./mini_agent/acp/server.py`
+
+**Usage:**
+- Open Zed's agent panel with `Ctrl+Shift+P` → "Agent: Toggle Panel"
+- Select "mini-agent" from the agent dropdown
+- Start conversations with Mini Agent directly in your editor
+
+## Usage Examples
+
+Here are a few examples of what Mini Agent can do.
+
+### Task Execution
+
+*In this demo, the agent is asked to create a simple, beautiful webpage and display it in the browser, showcasing the basic tool-use loop.*
+
+![Demo GIF 1: Basic Task Execution](docs/assets/demo1-task-execution.gif "Basic Task Execution Demo")
+
+### Using a Claude Skill (e.g., PDF Generation)
+
+*Here, the agent leverages a Claude Skill to create a professional document (like a PDF or DOCX) based on the user's request, demonstrating its advanced capabilities.*
+
+![Demo GIF 2: Claude Skill Usage](docs/assets/demo2-claude-skill.gif "Claude Skill Usage Demo")
+
+### Web Search & Summarization (MCP Tool)
+
+*This demo shows the agent using its web search tool to find up-to-date information online and summarize it for the user.*
+
+![Demo GIF 3: Web Search](docs/assets/demo3-web-search.gif "Web Search Demo")
+
+## Testing
+
+The project includes comprehensive test cases covering unit tests, functional tests, and integration tests.
+
+### Quick Run
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run core functionality tests
+pytest tests/test_agent.py tests/test_note_tool.py -v
+```
+
+### Test Coverage
+
+- ✅ **Unit Tests** - Tool classes, LLM client
+- ✅ **Functional Tests** - Session Note Tool, MCP loading
+- ✅ **Integration Tests** - Agent end-to-end execution
+- ✅ **External Services** - Git MCP Server loading
+
+
+## Troubleshooting
+
+### SSL Certificate Error
+
+If you encounter `[SSL: CERTIFICATE_VERIFY_FAILED]` error:
+
+**Quick fix for testing** (modify `mini_agent/llm.py`):
+```python
+# Line 50: Add verify=False to AsyncClient
+async with httpx.AsyncClient(timeout=120.0, verify=False) as client:
+```
+
+**Production solution**:
+```bash
+# Update certificates
+pip install --upgrade certifi
+
+# Or configure system proxy/certificates
+```
+
+### Module Not Found Error
+
+Make sure you're running from the project directory:
+```bash
+cd Mini-Agent
+python -m mini_agent.cli
+```
+
+## Related Documentation
+
+- [Development Guide](docs/DEVELOPMENT_GUIDE.md) - Detailed development and configuration guidance
+- [Production Guide](docs/PRODUCTION_GUIDE.md) - Best practices for production deployment
+
+## Community
+
+Join the MiniMax official community to get help, share ideas, and stay updated:
+
+- **WeChat Group**: Scan the QR code on [Contact Us](https://platform.minimaxi.com/docs/faq/contact-us) page to join
+
+## Contributing
+
+Issues and Pull Requests are welcome!
+
+- [Contributing Guide](CONTRIBUTING.md) - How to contribute
+- [Code of Conduct](CODE_OF_CONDUCT.md) - Community guidelines
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+
+## References
+
+- MiniMax API: https://platform.minimaxi.com/document
+- MiniMax-M2: https://github.com/MiniMax-AI/MiniMax-M2
+- Anthropic API: https://docs.anthropic.com/claude/reference
+- Claude Skills: https://github.com/anthropics/skills
+- MCP Servers: https://github.com/modelcontextprotocol/servers
+
+---
+
+**⭐ If this project helps you, please give it a Star!**

README_CN.md

@@ -0,0 +1,345 @@
+# Mini Agent
+
+[English](./README.md) | 中文
+
+**Mini Agent** 是一个极简但专业的演示项目，旨在展示使用 MiniMax M2.1 模型构建 Agent 的最佳实践。项目通过兼容 Anthropic 的 API，完全支持交错思维（interleaved thinking），从而解锁 M2 模型在处理长而复杂的任务时强大的推理能力。
+
+该项目具备一系列为稳健、智能的 Agent 开发而设计的特性：
+
+*   ✅ **完整的 Agent 执行循环**：一个完整可靠的执行框架，配备了文件系统和 Shell 操作的基础工具集。
+*   ✅ **持久化记忆**：通过内置的 **Session Note Tool**，Agent 能够在多个会话中保留关键信息。
+*   ✅ **智能上下文管理**：自动对会话历史进行摘要，可处理长达可配置 Token 上限的上下文，从而支持无限长的任务。
+*   ✅ **集成 Claude Skills**：内置 15 种专业技能，涵盖文档处理、设计、测试和开发等领域。
+*   ✅ **集成 MCP 工具**：原生支持 MCP 协议，可轻松接入知识图谱、网页搜索等工具。
+*   ✅ **全面的日志记录**：为每个请求、响应和工具执行提供详细日志，便于调试。
+*   ✅ **简洁明了的设计**：美观的命令行界面和易于理解的代码库，使其成为构建高级 Agent 的理想起点。
+
+## 目录
+
+- [Mini Agent](#mini-agent)
+  - [目录](#目录)
+  - [快速开始](#快速开始)
+    - [1. 获取 API Key](#1-获取-api-key)
+    - [2. 选择使用模式](#2-选择使用模式)
+      - [🚀 快速上手模式（推荐新手）](#-快速上手模式推荐新手)
+      - [🔧 开发模式](#-开发模式)
+  - [ACP \& Zed Editor 集成（可选）](#acp--zed-editor-集成可选)
+  - [使用示例](#使用示例)
+    - [任务执行](#任务执行)
+    - [使用 Claude Skill（例如：PDF 生成）](#使用-claude-skill例如pdf-生成)
+    - [网页搜索与摘要（MCP 工具）](#网页搜索与摘要mcp-工具)
+  - [测试](#测试)
+    - [快速运行](#快速运行)
+    - [测试覆盖范围](#测试覆盖范围)
+  - [常见问题](#常见问题)
+    - [SSL 证书错误](#ssl-证书错误)
+    - [模块未找到错误](#模块未找到错误)
+  - [相关文档](#相关文档)
+  - [社区](#社区)
+  - [贡献](#贡献)
+  - [许可证](#许可证)
+  - [参考资源](#参考资源)
+
+## 快速开始
+
+### 1. 获取 API Key
+
+MiniMax 提供国内和海外两个平台，请根据您的网络环境选择：
+
+| 版本       | 平台地址                                                       | API Base                   |
+| ---------- | -------------------------------------------------------------- | -------------------------- |
+| **国内版** | [https://platform.minimaxi.com](https://platform.minimaxi.com) | `https://api.minimaxi.com` |
+| **海外版** | [https://platform.minimax.io](https://platform.minimax.io)     | `https://api.minimax.io`   |
+
+**获取步骤：**
+1. 访问相应平台注册并登录
+2. 进入 **账户管理 > API 密钥**
+3. 点击 **"创建新密钥"**
+4. 复制并妥善保存（密钥仅显示一次）
+
+> 💡 **提示**：请记住您所选平台对应的 API Base 地址，后续配置时会用到。
+
+### 2. 选择使用模式
+
+**前置要求：安装 uv**
+
+两种使用模式都需要 uv。如果您尚未安装：
+
+```bash
+# macOS/Linux/WSL
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows (PowerShell)
+python -m pip install --user pipx
+python -m pipx ensurepath
+# 安装后需要重启 PowerShell
+
+# 安装完成后，重启终端或运行：
+source ~/.bashrc  # 或 ~/.zshrc (macOS/Linux)
+```
+
+我们提供两种使用模式，请根据您的需求选择：
+
+#### 🚀 快速上手模式（推荐新手）
+
+此模式适合希望快速体验 Mini Agent，而无需克隆代码仓库或修改代码的用户。
+
+**安装步骤：**
+
+```bash
+# 1. 直接从 GitHub 安装
+uv tool install git+https://github.com/MiniMax-AI/Mini-Agent.git
+
+# 2. 运行配置脚本（自动创建配置文件）
+# macOS/Linux:
+curl -fsSL https://raw.githubusercontent.com/MiniMax-AI/Mini-Agent/main/scripts/setup-config.sh | bash
+
+# Windows (PowerShell):
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/MiniMax-AI/Mini-Agent/main/scripts/setup-config.ps1" -OutFile "$env:TEMP\setup-config.ps1"
+powershell -ExecutionPolicy Bypass -File "$env:TEMP\setup-config.ps1"
+```
+
+> 💡 **提示**：如果您希望在本地进行开发或修改代码，请使用下方的"开发模式"。
+
+**配置步骤：**
+
+配置脚本会在 `~/.mini-agent/config/` 目录下创建配置文件，请编辑该文件：
+
+```bash
+# 编辑配置文件
+nano ~/.mini-agent/config/config.yaml
+```
+
+填入您的 API Key 和对应的 API Base：
+
+```yaml
+api_key: "YOUR_API_KEY_HERE"          # 填入第 1 步获取的 API Key
+api_base: "https://api.minimaxi.com"  # 国内版
+# api_base: "https://api.minimax.io"  # 海外版（如使用海外平台，请取消本行注释）
+model: "MiniMax-M2.1"
+```
+
+**���始使用：**
+
+```bash
+mini-agent                                    # 使用当前目录作为工作空间
+mini-agent --workspace /path/to/your/project  # 指定工作空间目录
+mini-agent --version                          # 查看版本信息
+
+# 管理命令
+uv tool upgrade mini-agent                    # 升级到最新版本
+uv tool uninstall mini-agent                  # 卸载工具（如需要）
+uv tool list                                  # 查看所有已安装的工具
+```
+
+#### 🔧 开发模式
+
+此模式适合需要修改代码、添加功能或进行调试的开发者。
+
+**安装与配置步骤：**
+
+```bash
+# 1. 克隆仓库
+git clone https://github.com/MiniMax-AI/Mini-Agent.git
+cd Mini-Agent
+
+# 2. 安装 uv（如果尚未安装）
+# macOS/Linux:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+# Windows (PowerShell):
+irm https://astral.sh/uv/install.ps1 | iex
+# 安装后需要重启终端
+
+# 3. 同步依赖
+uv sync
+
+# 替代方案: 手动安装依赖（如果不使用 uv）
+# pip install -r requirements.txt
+# 或者安装必需的包:
+# pip install tiktoken pyyaml httpx pydantic requests prompt-toolkit mcp
+
+# 4. 初始化 Claude Skills（可选）
+git submodule update --init --recursive
+
+# 5. 复制配置模板
+```
+
+**macOS/Linux:**
+```bash
+cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml
+```
+
+**Windows:**
+```powershell
+Copy-Item mini_agent\config\config-example.yaml mini_agent\config\config.yaml
+
+# 6. 编辑配置文件
+vim mini_agent/config/config.yaml  # 或使用您偏好的编辑器
+```
+
+填入您的 API Key 和对应的 API Base：
+
+```yaml
+api_key: "YOUR_API_KEY_HERE"          # 填入第 1 步获取的 API Key
+api_base: "https://api.minimaxi.com"  # 国内版
+# api_base: "https://api.minimax.io"  # 海外版（如使用海外平台，请修改此行）
+model: "MiniMax-M2.1"
+max_steps: 100
+workspace_dir: "./workspace"
+```
+
+> 📖 完整的配置指南，请参阅 [config-example.yaml](mini_agent/config/config-example.yaml)
+
+**运行方式：**
+
+选择您偏好的方式运行：
+
+```bash
+# 方式 1：作为模块直接运行（适合调试）
+uv run python -m mini_agent.cli
+
+# 方式 2：以可编辑模式安装（推荐）
+uv tool install -e .
+# 安装后，您可以在任何路径下运行，且代码更改会立即生效
+mini-agent
+mini-agent --workspace /path/to/your/project
+```
+
+> 📖 更多开发指引，请参阅 [开发指南](docs/DEVELOPMENT_GUIDE_CN.md)
+
+> 📖 更多生产部署指引，请参阅 [生产指南](docs/PRODUCTION_GUIDE_CN.md)
+
+## ACP & Zed Editor 集成（可选）
+
+Mini Agent 支持 [Agent Communication Protocol (ACP)](https://github.com/modelcontextprotocol/protocol)，可与 Zed 等代码编辑器集成。
+
+**在 Zed Editor 中设置：**
+
+1. 以开发模式或工具模式安装 Mini Agent
+2. 在您的 Zed `settings.json` 中添加：
+
+```json
+{
+  "agent_servers": {
+    "mini-agent": {
+      "command": "/path/to/mini-agent-acp"
+    }
+  }
+}
+```
+
+命令路径应为：
+- 通过 `uv tool install` 安装：使用 `which mini-agent-acp` 的输出结果
+- 开发模式：`./mini_agent/acp/server.py`
+
+**使用方法：**
+- 使用 `Ctrl+Shift+P` → "Agent: Toggle Panel" 打开 Zed 的 Agent 面板
+- 从 Agent 下拉列表中选择 "mini-agent"
+- 直接在编辑器中开始与 Mini Agent 对话
+
+## 使用示例
+
+这里有几个 Mini Agent 能力的演示。
+
+### 任务执行
+
+*在这个演示中，我们要求 Agent 创建一个简洁美观的网页并在浏览器中显示它，以此展示基础的工具使用循环。*
+
+![演示动图 1: 基础任务执行](docs/assets/demo1-task-execution.gif "基础任务执行演示")
+
+### 使用 Claude Skill（例如：PDF 生成）
+
+*这里，Agent 利用 Claude Skill 根据用户请求创建专业文档（如 PDF 或 DOCX），展示了其强大的高级能力。*
+
+![演示动图 2: Claude Skill 使用](docs/assets/demo2-claude-skill.gif "Claude Skill 使用演示")
+
+### 网页搜索与摘要（MCP 工具）
+
+*此演示展示了 Agent 如何使用其网页搜索工具在线查找最新信息，并为用户进行总结。*
+
+![演示动图 3: 网页搜索](docs/assets/demo3-web-search.gif "网页搜索演示")
+
+
+## 测试
+
+项目包含了覆盖单元测试、功能测试和集成测试的全面测试用例。
+
+### 快速运行
+
+```bash
+# 运行所有测试
+pytest tests/ -v
+
+# 仅运行核心功能测试
+pytest tests/test_agent.py tests/test_note_tool.py -v
+```
+
+### 测试覆盖范围
+
+- ✅ **单元测试** - 工具类、LLM 客户端
+- ✅ **功能测试** - Session Note Tool、MCP 加载
+- ✅ **集成测试** - Agent 端到端执行
+- ✅ **外部服务** - Git MCP 服务器加载
+
+
+## 常见问题
+
+### SSL 证书错误
+
+如果遇到 `[SSL: CERTIFICATE_VERIFY_FAILED]` 错误:
+
+**测试环境快速修复** (修改 `mini_agent/llm.py`):
+```python
+# 第 50 行: 给 AsyncClient 添加 verify=False
+async with httpx.AsyncClient(timeout=120.0, verify=False) as client:
+```
+
+**生产环境解决方案**:
+```bash
+# 更新证书
+pip install --upgrade certifi
+
+# 或配置系统代理/证书
+```
+
+### 模块未找到错误
+
+确保从项目目录运行:
+```bash
+cd Mini-Agent
+python -m mini_agent.cli
+```
+
+## 相关文档
+
+- [开发指南](docs/DEVELOPMENT_GUIDE_CN.md) - 详细的开发和配置指引
+- [生产环境指南](docs/PRODUCTION_DEPLOYMENT_GUIDE_CN.md) - 生产部署最佳实践
+
+## 社区
+
+加入 MiniMax 官方社区，获取帮助、分享想法、了解最新动态：
+
+- **微信交流群**：扫描 [联系我们](https://platform.minimaxi.com/docs/faq/contact-us) 页面的二维码加入官方交流群
+
+## 贡献
+
+我们欢迎并鼓励您提交 Issue 和 Pull Request！
+
+- [贡献指南](CONTRIBUTING.md) - 如何为项目做贡献
+- [行为准则](CODE_OF_CONDUCT.md) - 社区行为准则
+
+## 许可证
+
+本项目采用 [MIT 许可证](LICENSE) 授权。
+
+## 参考资源
+
+- MiniMax API: https://platform.minimaxi.com/document
+- MiniMax-M2: https://github.com/MiniMax-AI/MiniMax-M2
+- Anthropic API: https://docs.anthropic.com/claude/reference
+- Claude Skills: https://github.com/anthropics/skills
+- MCP Servers: https://github.com/modelcontextprotocol/servers
+
+---
+
+**⭐ 如果这个项目对您有帮助，请给它一个 Star！**

docs/DEVELOPMENT_GUIDE.md

@@ -0,0 +1,417 @@
+# Development Guide
+
+## Table of Contents
+
+- [Development Guide](#development-guide)
+  - [Table of Contents](#table-of-contents)
+  - [1. Project Architecture](#1-project-architecture)
+  - [2. Basic Usage](#2-basic-usage)
+    - [2.1 Interactive Commands](#21-interactive-commands)
+    - [2.2 Integrated MCP Tools](#22-integrated-mcp-tools)
+      - [Memory - Knowledge Graph Memory System](#memory---knowledge-graph-memory-system)
+      - [MiniMax Search - Web Search and Browse](#minimax-search---web-search-and-browse)
+  - [3. Extended Abilities](#3-extended-abilities)
+    - [3.1 Adding Custom Tools](#31-adding-custom-tools)
+      - [Steps](#steps)
+      - [Example](#example)
+    - [3.2 Adding MCP Tools](#32-adding-mcp-tools)
+    - [3.3 Customizing Note Storage](#33-customizing-note-storage)
+    - [3.4 Initialize Claude Skills (Recommended)](#34-initialize-claude-skills-recommended)
+    - [3.5 Adding a New Skill](#35-adding-a-new-skill)
+    - [3.6 Customizing System Prompt](#36-customizing-system-prompt)
+      - [What You Can Customize](#what-you-can-customize)
+  - [4. Troubleshooting](#4-troubleshooting)
+    - [4.1 Common Issues](#41-common-issues)
+      - [API Key Configuration Error](#api-key-configuration-error)
+      - [Dependency Installation Failure](#dependency-installation-failure)
+      - [MCP Tool Loading Failure](#mcp-tool-loading-failure)
+    - [4.2 Debugging Tips](#42-debugging-tips)
+      - [Enable Verbose Logging](#enable-verbose-logging)
+      - [Using the Python Debugger](#using-the-python-debugger)
+      - [Inspecting Tool Calls](#inspecting-tool-calls)
+
+---
+
+## 1. Project Architecture
+
+```
+mini-agent/
+├── mini_agent/              # Core source code
+│   ├── agent.py             # Main agent loop
+│   ├── llm.py               # LLM client
+│   ├── cli.py               # Command-line interface
+│   ├── config.py            # Configuration loading
+│   ├── tools/               # Tool implementations (file, bash, MCP, skills, etc.)
+│   └── skills/              # Claude Skills (submodule)
+├── tests/                   # Test code
+├── docs/                    # Documentation
+├── workspace/               # Working directory
+└── pyproject.toml           # Project configuration
+```
+
+## 2. Basic Usage
+
+### 2.1 Interactive Commands
+
+When running the agent in interactive mode (`mini-agent`), the following commands are available:
+
+| Command                | Description                                                 |
+| ---------------------- | ----------------------------------------------------------- |
+| `/exit`, `/quit`, `/q` | Exit the agent and display session statistics               |
+| `/help`                | Display help information and available commands             |
+| `/clear`               | Clear message history and start a new session               |
+| `/history`             | Show the current session message count                      |
+| `/stats`               | Display session statistics (steps, tool calls, tokens used) |
+
+### 2.2 Integrated MCP Tools
+
+This project comes with pre-configured MCP (Model Context Protocol) tools that extend the agent's capabilities:
+
+#### Memory - Knowledge Graph Memory System
+
+**Function**: Provides long-term memory storage and retrieval based on graph database
+
+**Status**: Enabled by default (`disabled: false`)
+
+**Configuration**: No API Key required, works out of the box
+
+**Capabilities**:
+- Store and retrieve information across sessions
+- Build knowledge graphs from conversations
+- Semantic search through stored memories
+
+---
+
+#### MiniMax Search - Web Search and Browse
+
+**Function**: Provides three powerful tools:
+- `search` - Web search capability
+- `parallel_search` - Execute multiple searches simultaneously
+- `browse` - Intelligent web browsing and content extraction
+
+**Status**: Disabled by default, needs configuration to enable
+
+**Configuration Example**
+
+```json
+{
+  "mcpServers": {
+    "minimax_search": {
+      "disabled": false,
+      "env": {
+        "JINA_API_KEY": "your-jina-api-key",
+        "SERPER_API_KEY": "your-serper-api-key",
+        "MINIMAX_TOKEN": "your-minimax-token"
+      }
+    }
+  }
+}
+```
+
+## 3. Extended Abilities
+
+### 3.1 Adding Custom Tools
+
+#### Steps
+
+1.  Create a new tool file under `mini_agent/tools/`.
+2.  Inherit from the `Tool` base class.
+3.  Implement the required properties and methods.
+4.  Register the tool during Agent initialization.
+
+#### Example
+
+```python
+# mini_agent/tools/my_tool.py
+from mini_agent.tools.base import Tool, ToolResult
+from typing import Dict, Any
+
+class MyTool(Tool):
+    @property
+    def name(self) -> str:
+        """A unique name for the tool."""
+        return "my_tool"
+    
+    @property
+    def description(self) -> str:
+        """A description for the LLM to understand the tool's purpose."""
+        return "My custom tool for doing something useful"
+    
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        """Parameter schema in JSON Schema format."""
+        return {
+            "type": "object",
+            "properties": {
+                "param1": {
+                    "type": "string",
+                    "description": "First parameter"
+                },
+                "param2": {
+                    "type": "integer",
+                    "description": "Second parameter",
+                    "default": 10
+                }
+            },
+            "required": ["param1"]
+        }
+    
+    async def execute(self, param1: str, param2: int = 10) -> ToolResult:
+        """
+        The main logic of the tool.
+        
+        Args:
+            param1: The first parameter.
+            param2: The second parameter, with a default value.
+        
+        Returns:
+            A ToolResult object.
+        """
+        try:
+            # Implement your logic here
+            result = f"Processed {param1} with param2={param2}"
+            
+            return ToolResult(
+                success=True,
+                content=result
+            )
+        except Exception as e:
+            return ToolResult(
+                success=False,
+                content=f"Error: {str(e)}"
+            )
+
+# In cli.py or agent initialization code
+from mini_agent.tools.my_tool import MyTool
+
+# Add the new tool when creating the Agent
+tools = [
+    ReadTool(workspace_dir),
+    WriteTool(workspace_dir),
+    MyTool(),  # Add your custom tool
+]
+
+agent = Agent(
+    llm=llm,
+    tools=tools,
+    max_steps=50
+)
+```
+
+### 3.2 Adding MCP Tools
+
+Edit `mcp.json` to add a new MCP Server:
+
+```json
+{
+  "mcpServers": {
+    "my_custom_mcp": {
+      "description": "My custom MCP server",
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@my-org/my-mcp-server"],
+      "env": {
+        "API_KEY": "your-api-key"
+      },
+      "disabled": false,
+      "notes": {
+        "description": "This is a custom MCP server.",
+        "api_key_url": "https://example.com/api-keys"
+      }
+    }
+  }
+}
+```
+
+### 3.3 Customizing Note Storage
+
+To replace the storage backend for the `SessionNoteTool`:
+
+```python
+# Current implementation: JSON file
+class SessionNoteTool:
+    def __init__(self, memory_file: str = "./workspace/.agent_memory.json"):
+        self.memory_file = Path(memory_file)
+    
+    async def _save_notes(self, notes: List[Dict]):
+        with open(self.memory_file, 'w') as f:
+            json.dump(notes, f, indent=2, ensure_ascii=False)
+
+# Example extension: PostgreSQL
+class PostgresNoteTool(Tool):
+    def __init__(self, db_url: str):
+        self.db = PostgresDB(db_url)
+    
+    async def _save_notes(self, notes: List[Dict]):
+        await self.db.execute(
+            "INSERT INTO notes (content, category, timestamp) VALUES ($1, $2, $3)",
+            notes
+        )
+
+# Example extension: Vector Database
+class MilvusNoteTool(Tool):
+    def __init__(self, milvus_host: str):
+        self.vector_db = MilvusClient(host=milvus_host)
+    
+    async def _save_notes(self, notes: List[Dict]):
+        # Generate embeddings
+        embeddings = await self.get_embeddings([n["content"] for n in notes])
+        
+        # Store in the vector database
+        await self.vector_db.insert(
+            collection="agent_notes",
+            data=notes,
+            embeddings=embeddings
+        )
+```
+
+### 3.4 Initialize Claude Skills (Recommended) 
+
+This project integrates Claude's official skills repository via git submodule. Initialize it after first clone:
+
+```bash
+# Initialize submodule
+git submodule update --init --recursive
+```
+
+Skills provide 20+ professional capabilities, making the Agent work like a professional:
+
+- 📄 **Document Processing**: Create and edit PDF, DOCX, XLSX, PPTX
+- 🎨 **Design Creation**: Generate artwork, posters, GIF animations
+- 🧪 **Development & Testing**: Web automation testing (Playwright), MCP server development
+- 🏢 **Enterprise Applications**: Internal communication, brand guidelines, theme customization
+
+✨ **This is one of the core highlights of this project.** For details, see the "Configure Skills" section below.
+
+**More information:**
+
+- [Claude Skills Official Documentation](https://docs.claude.com/zh-CN/docs/agents-and-tools/agent-skills)
+- [Anthropic Blog: Equipping agents for the real world](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
+
+### 3.5 Adding a New Skill
+
+Create a custom Skill:
+
+```bash
+# Create a new skill directory under skills/
+mkdir skills/my-custom-skill
+cd skills/my-custom-skill
+
+# Create the SKILL.md file
+cat > SKILL.md << 'EOF'
+---
+name: my-custom-skill
+description: My custom skill for handling specific tasks.
+---
+
+# Overview
+
+This skill provides the following capabilities:
+- Capability 1
+- Capability 2
+
+# Usage
+
+1. Step one...
+2. Step two...
+
+# Best Practices
+
+- Practice 1
+- Practice 2
+
+# FAQ
+
+Q: Question 1
+A: Answer 1
+```
+
+The new Skill will be automatically loaded and recognized by the Agent.
+
+### 3.6 Customizing System Prompt
+
+The system prompt (`system_prompt.md`) defines the Agent's behavior, capabilities, and working guidelines. You can customize it to tailor the Agent for specific use cases.
+
+#### What You Can Customize
+
+1. **Core Capabilities**: Add or modify tool descriptions
+2. **Working Guidelines**: Define custom workflows and best practices
+3. **Domain-Specific Knowledge**: Add expertise in specific areas
+4. **Communication Style**: Adjust how the Agent interacts with users
+5. **Task Priorities**: Set preferences for how tasks should be approached
+
+After modifying `system_prompt.md`, be sure to restart the Agent to apply changes
+
+## 4. Troubleshooting
+
+### 4.1 Common Issues
+
+#### API Key Configuration Error
+
+```bash
+# Error message
+Error: Invalid API key
+
+# Solution
+1. Check that the API key in `config.yaml` is correct.
+2. Ensure there are no extra spaces or quotes.
+3. Verify that the API key has not expired.
+```
+
+#### Dependency Installation Failure
+
+```bash
+# Error message
+uv sync failed
+
+# Solution
+1. Update uv to the latest version: `uv self update`
+2. Clear the cache: `uv cache clean`
+3. Try syncing again: `uv sync`
+```
+
+#### MCP Tool Loading Failure
+
+```bash
+# Error message
+Failed to load MCP server
+
+# Solution
+1. Check the configuration in `mcp.json` is correct.
+2. Ensure Node.js is installed (required for most MCP tools).
+3. Verify that any required API keys are configured.
+4. View detailed logs: `pytest tests/test_mcp.py -v -s`
+```
+
+### 4.2 Debugging Tips
+
+#### Enable Verbose Logging
+
+```python
+# At the beginning of cli.py or a test file
+import logging
+
+logging.basicConfig(
+    level=logging.DEBUG,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+```
+
+#### Using the Python Debugger
+
+```python
+# Set a breakpoint in your code
+import pdb; pdb.set_trace()
+
+# Or use ipdb for a better experience
+import ipdb; ipdb.set_trace()
+```
+
+#### Inspecting Tool Calls
+
+```python
+# Add logging in the Agent to see tool interactions
+logger.debug(f"Tool call: {tool_call.name}")
+logger.debug(f"Tool arguments: {tool_call.arguments}")
+logger.debug(f"Tool result: {result.content[:200]}")
+```

docs/DEVELOPMENT_GUIDE_CN.md

@@ -0,0 +1,420 @@
+# 开发指南
+
+
+## 目录
+
+- [开发指南](#开发指南)
+  - [目录](#目录)
+  - [1. 项目架构](#1-项目架构)
+  - [2. 基础使用](#2-基础使用)
+    - [2.1 交互式命令](#21-交互式命令)
+    - [2.2 已集成的 MCP 工具](#22-已集成的-mcp-工具)
+      - [Memory - 知识图谱记忆系统](#memory---知识图谱记忆系统)
+      - [MiniMax Search - 网页搜索与浏览](#minimax-search---网页搜索与浏览)
+  - [3. 扩展能力](#3-扩展能力)
+    - [3.1 添加自定义工具](#31-添加自定义工具)
+      - [步骤](#步骤)
+      - [示例](#示例)
+    - [3.2 添加 MCP 工具](#32-添加-mcp-工具)
+    - [3.3 自定义存储](#33-自定义存储)
+    - [3.4 初始化 Claude Skills（推荐）](#34-初始化-claude-skills推荐)
+    - [3.5 添加新的Skill](#35-添加新的skill)
+    - [3.6 自定义系统提示词](#36-自定义系统提示词)
+      - [可定制内容包括：](#可定制内容包括)
+  - [4. 故障排查](#4-故障排查)
+    - [4.1 常见问题](#41-常见问题)
+      - [API 密钥配置错误](#api-密钥配置错误)
+      - [依赖安装失败](#依赖安装失败)
+      - [MCP 工具加载失败](#mcp-工具加载失败)
+    - [4.2 调试技巧](#42-调试技巧)
+      - [启用 Debug 日志](#启用-debug-日志)
+      - [使用 Python 调试器](#使用-python-调试器)
+      - [监控工具调用](#监控工具调用)
+
+---
+
+## 1. 项目架构
+
+```
+mini-agent/
+├── mini_agent/              # 核心源代码
+│   ├── agent.py             # 主 Agent 循环
+│   ├── llm.py               # LLM 客户端
+│   ├── cli.py               # 命令行接口
+│   ├── config.py            # 配置加载
+│   ├── tools/               # 工具实现（文件、Bash、MCP、技能等）
+│   └── skills/              # Claude 技能集（子模块）
+├── tests/                   # 测试代码
+├── docs/                    # 文档
+├── workspace/               # 工作目录
+└── pyproject.toml           # 项目配置
+```
+
+## 2. 基础使用
+
+### 2.1 交互式命令
+
+在交互模式 (通过 `mini-agent` 启动) 下运行 Agent 时，您可以使用以下命令：
+
+| 命令                   | 说明                                             |
+| ---------------------- | ------------------------------------------------ |
+| `/exit`, `/quit`, `/q` | 退出 Agent 并显示会话统计信息                    |
+| `/help`                | 显示帮助信息和可用命令                           |
+| `/clear`               | 清除消息历史并开始新会话                         |
+| `/history`             | 显示当前会话的消息数量                           |
+| `/stats`               | 显示会话统计信息（步数、工具调用、使用的 Token） |
+
+### 2.2 已集成的 MCP 工具
+
+本项目预先集成了以下 MCP (模型上下文协议) 工具，用以扩展 Agent 的能力：
+
+#### Memory - 知识图谱记忆系统
+
+**功能**：基于图数据库，为 Agent 提供长期记忆的存储与检索能力。
+
+**状态**：默认启用
+
+**配置**：无需 API Key，开箱即用
+
+**能力**：
+- 跨会话存储并检索信息
+- 根据对话内容构建知识图谱
+- 对已存储的记忆进行语义搜索
+
+---
+
+#### MiniMax Search - 网页搜索与浏览
+
+**功能**：提供三大强大工具：
+- `search` - 网页搜索
+- `parallel_search` - 并行执行多个搜索任务
+- `browse` - 智能网页浏览与内容提取
+
+**状态**：默认禁用，需要配置 API Key 后方可启用。
+
+**配置示例**：
+
+```json
+{
+  "mcpServers": {
+    "minimax_search": {
+      "disabled": false,
+      "env": {
+        "JINA_API_KEY": "your-jina-api-key",
+        "SERPER_API_KEY": "your-serper-api-key",
+        "MINIMAX_API_KEY": "your-minimax-token"
+      }
+    }
+  }
+}
+```
+
+## 3. 扩展能力
+
+### 3.1 添加自定义工具
+
+#### 步骤
+
+1.  在 `mini_agent/tools/` 目录下创建一个新的 Python 文件。
+2.  在文件中定义一个新类，并继承 `Tool` 基类。
+3.  在类中实现所需的属性和方法。
+4.  在 Agent 初始化时注册你的新工具。
+
+#### 示例
+
+```python
+# mini_agent/tools/my_tool.py
+from mini_agent.tools.base import Tool, ToolResult
+from typing import Dict, Any
+
+class MyTool(Tool):
+    @property
+    def name(self) -> str:
+        """工具的唯一名称，需保持独一无二。"""
+        return "my_tool"
+    
+    @property
+    def description(self) -> str:
+        """工具用途的详细描述，帮助 LLM 理解其功能。"""
+        return "我的自定义工具，用于完成特定任务"
+    
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        """参数模式（JSON Schema 格式）。"""
+        return {
+            "type": "object",
+            "properties": {
+                "param1": {
+                    "type": "string",
+                    "description": "第一���参数"
+                },
+                "param2": {
+                    "type": "integer",
+                    "description": "第二个参数",
+                    "default": 10
+                }
+            },
+            "required": ["param1"]
+        }
+    
+    async def execute(self, param1: str, param2: int = 10) -> ToolResult:
+        """
+        工具执行的核心逻辑。
+        
+        Args:
+            param1: 参数一。
+            param2: 参数二，包含默认值。
+        
+        Returns:
+            返回一个 ToolResult 对象。
+        """
+        try:
+            # 在此实现你的逻辑
+            result = f"处理了 {param1}，param2={param2}"
+            
+            return ToolResult(
+                success=True,
+                content=result
+            )
+        except Exception as e:
+            return ToolResult(
+                success=False,
+                content=f"错误: {str(e)}"
+            )
+
+# 在 cli.py 或 Agent 的初始化代码中
+from mini_agent.tools.my_tool import MyTool
+
+# 创建 Agent 实例时，将新工具加入列表
+tools = [
+    ReadTool(workspace_dir),
+    WriteTool(workspace_dir),
+    MyTool(),  # 添加您的自定义工具
+]
+
+agent = Agent(
+    llm=llm,
+    tools=tools,
+    max_steps=50
+)
+```
+
+### 3.2 添加 MCP 工具
+
+编辑 `mcp.json` 文件，即可添加新的 MCP 服务器：
+
+```json
+{
+  "mcpServers": {
+    "my_custom_mcp": {
+      "description": "我的自定义 MCP 服务器",
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@my-org/my-mcp-server"],
+      "env": {
+        "API_KEY": "your-api-key"
+      },
+      "disabled": false,
+      "notes": {
+        "description": "这是一个自定义 MCP 服务器。",
+        "api_key_url": "https://example.com/api-keys"
+      }
+    }
+  }
+}
+```
+
+### 3.3 自定义存储
+
+您可以替换 `SessionNoteTool` 的默认存储实现，以对接不同的数据后端：
+
+```python
+# 默认实现：JSON 文件
+class SessionNoteTool:
+    def __init__(self, memory_file: str = "./workspace/.agent_memory.json"):
+        self.memory_file = Path(memory_file)
+    
+    async def _save_notes(self, notes: List[Dict]):
+        with open(self.memory_file, 'w') as f:
+            json.dump(notes, f, indent=2, ensure_ascii=False)
+
+# 扩展示例：使用 PostgreSQL 存储
+class PostgresNoteTool(Tool):
+    def __init__(self, db_url: str):
+        self.db = PostgresDB(db_url)
+    
+    async def _save_notes(self, notes: List[Dict]):
+        await self.db.execute(
+            "INSERT INTO notes (content, category, timestamp) VALUES ($1, $2, $3)",
+            notes
+        )
+
+# 扩展示例：使用向量数据库存储
+class MilvusNoteTool(Tool):
+    def __init__(self, milvus_host: str):
+        self.vector_db = MilvusClient(host=milvus_host)
+    
+    async def _save_notes(self, notes: List[Dict]):
+        # 生成内容的嵌入向量
+        embeddings = await self.get_embeddings([n["content"] for n in notes])
+        
+        # 将笔记和向量存入向量数据库
+        await self.vector_db.insert(
+            collection="agent_notes",
+            data=notes,
+            embeddings=embeddings
+        )
+```
+
+### 3.4 初始化 Claude Skills（推荐）
+
+本项目通过 Git Submodule 的方式集成了 Claude 官方技能库。首次克隆项目后，请执行以下命令来初始化技能库：
+
+```bash
+# 初始化并拉取技能库子模块
+git submodule update --init --recursive
+```
+
+Skills 库提供了超过20种专业能力，能让 Agent 如同行业专家般处理复杂任务：
+
+- 📄 **文档处理**：轻松创建和编辑 PDF、DOCX、XLSX、PPTX 等格式的文档。
+- 🎨 **设计创作**：生成富有创意的艺术作品、海报和 GIF 动画。
+- 🧪 **开发与测试**：支持 Web 自动化测试 (Playwright) 和 MCP 服务器开发。
+- 🏢 **企业应用**：高效处理内部沟通、品牌指南应用和主题定制等任务。
+
+✨ **这是本项目的核心亮点之一。**
+
+**更多信息：**
+
+- [Claude Skills 官方文档](https://docs.claude.com/zh-CN/docs/agents-and-tools/agent-skills)
+- [Anthropic 博客：为真实世界装备智能体](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
+
+### 3.5 添加新的Skill
+
+您可以按照以下步骤创建自定义 Skill：
+
+```bash
+# 在 skills/ 目录下为您的新技能创建一个目录
+mkdir skills/my-custom-skill
+cd skills/my-custom-skill
+
+# 创建技能描述文件 SKILL.md
+cat > SKILL.md << 'EOF'
+---
+name: my-custom-skill
+description: 这是一个自定义技能，用于处理特定任务。
+---
+
+# 概述
+
+该技能主要提供以下功能：
+- 功能 1
+- 功能 2
+
+# 使用方法
+
+1. 第一步...
+2. 第二步...
+
+# 最佳实践
+
+- 实践 1
+- 实践 2
+
+# 常见问题
+
+问：问题 1
+答：答案 1
+EOF
+```
+
+完成以上步骤后，Agent 将在下次启动时自动加载并识别这项新技能。
+
+### 3.6 自定义系统提示词
+
+系统提示词文件 (`system_prompt.md`) 定义了 Agent 的核心行为、能力边界和工作指南。您可以根据具体应用场景，对其进行深度定制。
+
+#### 可定制内容包括：
+
+1.  **核心能力**：添加或修改工具的描述，以影响 Agent 的工具选择。
+2.  **工作指南**：定义特定的工作流程或决策偏好。
+3.  **领域专业知识**：注入特定领域的知识，提升 Agent 的专业性。
+4.  **沟通风格**：调整 Agent 与用户交互时的语气和风格。
+5.  **任务优先级**：设定处理任务时的优先级和策略。
+
+完成修改后，请重启 Agent 以使新配置生效。
+
+## 4. 故障排查
+
+### 4.1 常见问题
+
+#### API 密钥配置错误
+
+```bash
+# 错误消息
+Error: Invalid API key
+
+# 解决方法
+1. 检查 `config.yaml` 文件中的 API 密钥是否填写正确。
+2. 确保密钥前后没有多余的空格或引号。
+3. 确认该 API 密钥是否仍在有效期内。
+```
+
+#### 依赖安装失败
+
+```bash
+# 错误消息
+uv sync failed
+
+# 解决方法
+1. 升级 uv 至最新版本：`uv self update`
+2. 清理 uv 缓存：`uv cache clean`
+3. 再次尝试同步依赖：`uv sync`
+```
+
+#### MCP 工具加载失败
+
+```bash
+# 错误消息
+Failed to load MCP server
+
+# 解决方法
+1. 检查 `mcp.json` 文件中的服务器配置是否正确。
+2. 确保您的开发环境已安装 Node.js (大部分 MCP 工具的运行需要)。
+3. 确认所需服务的 API 密钥已正确配置。
+4. 运行 MCP 测试并查看详细日志：`pytest tests/test_mcp.py -v -s`
+```
+
+### 4.2 调试技巧
+
+#### 启用 Debug 日志
+
+```python
+# 在 cli.py 或相关测试文件的开头添加以下代码：
+import logging
+
+logging.basicConfig(
+    level=logging.DEBUG,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+```
+
+#### 使用 Python 调试器
+
+```python
+# 在需要暂停执行的代码行处插入断点：
+import pdb; pdb.set_trace()
+
+# 或者使用 ipdb 以获得更佳的调试体验：
+import ipdb; ipdb.set_trace()
+```
+
+#### 监控工具调用
+
+```python
+# 在 Agent 代码中添加日志，以便实时查看工具的调用详情：
+logger.debug(f"工具调用: {tool_call.name}")
+logger.debug(f"工具参数: {tool_call.arguments}")
+logger.debug(f"工具结果: {result.content[:200]}")
+```
+

docs/PRODUCTION_GUIDE.md

@@ -0,0 +1,162 @@
+# Agent Production Guide
+
+> A Complete Guide from Demo to Production
+
+## Table of Contents
+
+- [1. Demo Features](#1-demo-features)
+- [2. Upgrade Directions](#2-upgrade-directions)
+- [3. Production Deployment](#3-production-deployment)
+
+---
+
+## 1. Demo Features
+
+This project is a **teaching-level demo** that demonstrates the core concepts and execution flow of an Agent. To reach production level, many complex issues still need to be addressed.
+
+### What We've Implemented (Demo Level)
+
+| Feature                  | Demo Implementation                   |
+| --------------------- | --------------------------- |
+| **Context Management** | ✅ Simple persistence via SessionNoteTool with file storage; basic summarization when approaching context window limit |
+| **Tool Calling**          | ✅ Basic Read/Write/Edit/Bash |
+| **Error Handling**          | ✅ Basic exception catching              |
+| **Logging**              | ✅ Simple print output           |
+
+
+## 2. Upgrade Directions
+
+### 2.1 Advanced Context Management
+
+- Introduce distributed file systems for unified context persistence management and backup
+- Use more precise methods for token counting
+- Introduce more strategies for message compression, including keeping the most recent N messages, preserving fixed metadata, prompt optimization for summarization, introducing recall systems, etc.
+
+### 2.2 Model Fallback Mechanism
+
+Currently using a single fixed model (MiniMax-M2.1), which will directly report errors on failure.
+
+- Introduce a model pool by configuring multiple model accounts to improve availability
+- Introduce automatic health checks, failure removal, circuit breaker strategies for the model pool
+
+### 2.3 Model Hallucination Detection and Correction
+
+Currently directly trusts model output without validation mechanism
+
+- Perform security checks on input parameters for certain tool calls to prevent high-risk actions
+- Perform reflection on results from certain tool calls to check if they are reasonable
+
+## 3. Production Deployment
+
+### 3.1 Container Deployment Recommendations
+
+We recommend using K8s/Docker environments for Agent deployment. Containerized deployment has the following advantages:
+
+- **Resource Isolation**: Each Agent instance runs in an independent container without interference
+- **Elastic Scaling**: Automatically adjust instance count based on load
+- **Version Management**: Easy rollback and canary releases
+- **Environment Consistency**: Development, testing, and production environments are completely consistent
+
+### 3.2 Resource Limit Configuration
+
+#### 3.2.1 CPU and Memory Limits
+
+To prevent the Agent from consuming excessive CPU/Memory resources and affecting the host, CPU and memory limits must be set:
+
+**Docker Configuration Example**:
+```yaml
+# docker-compose.yml
+services:
+  agent:
+    image: agent-demo:latest
+    deploy:
+      resources:
+        limits:
+          cpus: '2.0'      # Maximum 2 CPU cores
+          memory: 2G       # Maximum 2GB memory
+        reservations:
+          cpus: '0.5'      # Guarantee at least 0.5 cores
+          memory: 512M     # Guarantee at least 512MB
+```
+
+#### 3.2.2 Disk Limits
+
+Agents may generate large amounts of temporary files and log files, so disk usage needs to be limited:
+
+**Docker Volume Configuration**:
+```yaml
+# docker-compose.yml
+services:
+  agent:
+    volumes:
+      - type: tmpfs
+        target: /tmp
+        tmpfs:
+          size: 1G         # Maximum 1GB for temporary files
+      - type: volume
+        source: agent-data
+        target: /app/data
+        volume:
+          driver_opts:
+            size: 5G       # Maximum 5GB for data volume
+```
+
+
+### 3.3 Linux Account Permission Restrictions
+
+#### 3.3.1 Principle of Least Privilege
+
+**Never run the Agent as root user**, as this poses serious security risks.
+
+**Dockerfile Best Practices**:
+```dockerfile
+FROM python:3.11-slim
+
+# Install necessary system tools
+RUN apt-get update && apt-get install -y \
+    git \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.cargo/bin:$PATH"
+
+# Create non-privileged user
+RUN groupadd -r agent && useradd -r -g agent agent
+
+# Set working directory
+WORKDIR /app
+
+# Option 1: Clone from Git repository (for public repos)
+RUN git clone https://github.com/MiniMax-AI/agent-demo.git . && \
+    chown -R agent:agent /app
+
+# Option 2: Copy code from local (for private deployments)
+# COPY --chown=agent:agent . /app
+
+# Switch to non-privileged user before installing dependencies
+USER agent
+
+# Sync dependencies using uv
+RUN uv sync
+
+# Start the application
+CMD ["uv", "run", "mini-agent"]
+```
+
+#### 3.3.2 File System Permissions
+
+Restrict the Agent to only access necessary directories:
+
+```bash
+# Create restricted workspace directory
+mkdir -p /app/workspace
+chown agent:agent /app/workspace
+chmod 750 /app/workspace  # Owner: read/write/execute, Group: read/execute
+
+# Restrict access to sensitive directories
+chmod 700 /etc/agent      # Config directory only accessible by owner
+chmod 600 /etc/agent/*.yaml  # Config files only readable/writable by owner
+```
+

docs/PRODUCTION_GUIDE_CN.md

@@ -0,0 +1,161 @@
+# Agent 生产环境指南
+
+> 从 Demo 到生产环境的实践指南
+
+## 目录
+
+- [1. Demo功能实现](#1-demo功能)
+- [2. 可升级方向](#2-可升级方向)
+- [3. 生产部署](#3-生产部署)
+
+---
+
+## 1. Demo 功能概述
+
+本项目是一个**教学级 Demo**，旨在演示 Agent 的核心概念与基本执行流程。要在生产环境中使用，还需要解决一系列复杂问题。
+
+### Demo 实现的功能
+
+| 功能                  | Demo 实现                   |
+| --------------------- | --------------------------- |
+| **上下文管理** | ✅ 通过 `SessionNoteTool` 以文件形式实现了简单的上下文持久化；当接近上下文窗口上限时，会进行简单的摘要处理。 |
+| **工具调用**          | ✅ 提供了基础的 Read/Write/Edit/Bash 工具。 |
+| **错误处理**          | ✅ 实现了基础的异常捕获机制。              |
+| **日志**              | ✅ 使用简单的 `print` 函数输出日志。           |
+
+
+## 2. 升级与拓展方向
+
+### 2.1 高级上下文管理
+
+- **引入分布式文件系统**：对上下文进行统一的持久化管理和备份。
+- **优化 Token 计算**：使用更精确的方式计算 Token 数量。
+- **丰富消息压缩策略**：引入更丰富的消息压缩策略，例如保留最近 N 条消息、保留核心元信息、优化摘要 Prompt，或集成召回系统等。
+
+### 2.2 模型回退机制
+
+当前 Demo 固定使用单一模型（MiniMax-M2.1），调用失败时会直接报错。
+
+- **建立模型池**：配置多个模型账号，建立模型池以提高服务可用性。
+- **引入高可用策略**：为模型池引入自动健康检测、故障节点切换、熔断等高可用策略。
+
+### 2.3 模型幻觉的检测与修正
+
+当前 Demo 完全信任模型输出，缺乏验证机制。
+
+- **输入参数安全检查**：对部分工具的调用参数进行安全性检查，防止执行高危操作。
+- **输出结果合理性检查**：对部分工具的调用结果进行反思（Self-reflection），检查其合理性。
+
+## 3. 生产环境部署
+
+### 3.1 容器化部署建议
+
+我们推荐使用 Kubernetes 或 Docker 环境来部署 Agent。容器化部署具有以下优势：
+
+- **资源隔离**：每个 Agent 实例运行在独立的容器中，互不干扰。
+- **弹性扩展**：根据负载自动调整实例数量。
+- **版本管理**：便于快速回滚和灰度发布。
+- **环境一致性**：开发、测试、生产环境完全一致。
+
+### 3.2 资源限制
+
+#### 3.2.1 CPU 与内存限制
+
+为防止 Agent 实例占用过多资源而影响宿主机，您必须为其设置 CPU 和内存的限制：
+
+**Docker 配置示例**：
+```yaml
+# docker-compose.yml
+services:
+  agent:
+    image: agent-demo:latest
+    deploy:
+      resources:
+        limits:
+          cpus: '2.0'      # 最多使用 2 个 CPU 核心
+          memory: 2G       # 最多使用 2GB 内存
+        reservations:
+          cpus: '0.5'      # 保证至少 0.5 个核心
+          memory: 512M     # 保证至少 512MB
+```
+
+#### 3.2.2 磁盘限制
+
+Agent 运行过程中可能会产生大量的临时文件和日志，因此需要限制其磁盘使用量：
+
+**Docker Volume 配置**：
+```yaml
+# docker-compose.yml
+services:
+  agent:
+    volumes:
+      - type: tmpfs
+        target: /tmp
+        tmpfs:
+          size: 1G         # 临时文件最多 1GB
+      - type: volume
+        source: agent-data
+        target: /app/data
+        volume:
+          driver_opts:
+            size: 5G       # 数据卷最多 5GB
+```
+
+
+### 3.3 Linux 账户权限限制
+
+#### 3.3.1 最小权限原则
+
+**请勿使用 root 用户运行 Agent**，这会带来严重的安全风险。
+
+**Dockerfile 最佳实践**：
+```dockerfile
+FROM python:3.11-slim
+
+# 安装必要的系统工具
+RUN apt-get update && apt-get install -y \
+    git \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# 安装 uv
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.cargo/bin:$PATH"
+
+# 创建非特权用户
+RUN groupadd -r agent && useradd -r -g agent agent
+
+# 设置工作目录
+WORKDIR /app
+
+# 方案1：从 Git 仓库克隆（适用于公开仓库）
+RUN git clone https://github.com/MiniMax-AI/agent-demo.git . && \
+    chown -R agent:agent /app
+
+# 方案2：从本地复制代码（适用于私有部署）
+# COPY --chown=agent:agent . /app
+
+# 切换到非特权用户后安装依赖
+USER agent
+
+# 使用 uv 同步依赖
+RUN uv sync
+
+# 启动应用
+CMD ["uv", "run", "mini-agent"]
+```
+
+#### 3.3.2 文件系统权限
+
+您应限制 Agent 只能访问必要的目录：
+
+```bash
+# 创建受限的工作目录
+mkdir -p /app/workspace
+chown agent:agent /app/workspace
+chmod 750 /app/workspace  # 所有者读写执行，组只读执行
+
+# 限制敏感目录的访问
+chmod 700 /etc/agent      # 配置目录只有所有者能访问
+chmod 600 /etc/agent/*.yaml  # 配置文件只有所有者能读写
+```

examples/01_basic_tools.py

@@ -0,0 +1,137 @@
+"""Example 1: Basic Tools Usage
+
+This example demonstrates how to use the basic tools:
+- ReadTool: Read file contents
+- WriteTool: Create new files
+- EditTool: Edit existing files
+- BashTool: Execute bash commands
+
+Based on: tests/test_tools.py
+"""
+
+import asyncio
+import tempfile
+from pathlib import Path
+
+from mini_agent.tools import BashTool, EditTool, ReadTool, WriteTool
+
+
+async def demo_write_tool():
+    """Demo: Write a new file."""
+    print("\n" + "=" * 60)
+    print("Demo 1: WriteTool - Create a new file")
+    print("=" * 60)
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        file_path = Path(tmpdir) / "hello.txt"
+
+        tool = WriteTool()
+        result = await tool.execute(
+            path=str(file_path), content="Hello, Mini Agent!\nThis is a test file."
+        )
+
+        if result.success:
+            print(f"✅ File created: {file_path}")
+            print(f"Content:\n{file_path.read_text()}")
+        else:
+            print(f"❌ Failed: {result.error}")
+
+
+async def demo_read_tool():
+    """Demo: Read a file."""
+    print("\n" + "=" * 60)
+    print("Demo 2: ReadTool - Read file contents")
+    print("=" * 60)
+
+    with tempfile.NamedTemporaryFile(mode="w", delete=False, suffix=".txt") as f:
+        f.write("Line 1: Hello\nLine 2: World\nLine 3: Mini Agent")
+        temp_path = f.name
+
+    try:
+        tool = ReadTool()
+        result = await tool.execute(path=temp_path)
+
+        if result.success:
+            print(f"✅ File read successfully")
+            print(f"Content:\n{result.content}")
+        else:
+            print(f"❌ Failed: {result.error}")
+    finally:
+        Path(temp_path).unlink()
+
+
+async def demo_edit_tool():
+    """Demo: Edit an existing file."""
+    print("\n" + "=" * 60)
+    print("Demo 3: EditTool - Edit file content")
+    print("=" * 60)
+
+    with tempfile.NamedTemporaryFile(mode="w", delete=False, suffix=".txt") as f:
+        f.write("Python is great!\nI love Python programming.")
+        temp_path = f.name
+
+    try:
+        print(f"Original content:\n{Path(temp_path).read_text()}\n")
+
+        tool = EditTool()
+        result = await tool.execute(
+            path=temp_path, old_str="Python", new_str="Agent"
+        )
+
+        if result.success:
+            print(f"✅ File edited successfully")
+            print(f"New content:\n{Path(temp_path).read_text()}")
+        else:
+            print(f"❌ Failed: {result.error}")
+    finally:
+        Path(temp_path).unlink()
+
+
+async def demo_bash_tool():
+    """Demo: Execute bash commands."""
+    print("\n" + "=" * 60)
+    print("Demo 4: BashTool - Execute bash commands")
+    print("=" * 60)
+
+    tool = BashTool()
+
+    # Example 1: List files
+    print("\nCommand: ls -la")
+    result = await tool.execute(command="ls -la")
+    if result.success:
+        print(f"✅ Command executed successfully")
+        print(f"Output:\n{result.content[:200]}...")
+
+    # Example 2: Get current directory
+    print("\nCommand: pwd")
+    result = await tool.execute(command="pwd")
+    if result.success:
+        print(f"✅ Current directory: {result.content.strip()}")
+
+    # Example 3: Echo
+    print("\nCommand: echo 'Hello from BashTool!'")
+    result = await tool.execute(command="echo 'Hello from BashTool!'")
+    if result.success:
+        print(f"✅ Output: {result.content.strip()}")
+
+
+async def main():
+    """Run all demos."""
+    print("=" * 60)
+    print("Basic Tools Usage Examples")
+    print("=" * 60)
+    print("\nThese examples show how to use the core tools directly.")
+    print("In a real agent scenario, the LLM decides which tools to use.\n")
+
+    await demo_write_tool()
+    await demo_read_tool()
+    await demo_edit_tool()
+    await demo_bash_tool()
+
+    print("\n" + "=" * 60)
+    print("All demos completed! ✅")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/02_simple_agent.py

@@ -0,0 +1,212 @@
+"""Example 2: Simple Agent Usage
+
+This example demonstrates how to create and run a basic agent
+to perform simple file operations.
+
+Based on: tests/test_agent.py
+"""
+
+import asyncio
+import tempfile
+from pathlib import Path
+
+from mini_agent import LLMClient
+from mini_agent.agent import Agent
+from mini_agent.config import Config
+from mini_agent.tools import BashTool, EditTool, ReadTool, WriteTool
+
+
+async def demo_file_creation():
+    """Demo: Agent creates a file based on user request."""
+    print("\n" + "=" * 60)
+    print("Demo: Agent-Driven File Creation")
+    print("=" * 60)
+
+    # Load configuration
+    config_path = Path("mini_agent/config/config.yaml")
+    if not config_path.exists():
+        print("❌ config.yaml not found. Please set up your API key first.")
+        print("   Run: cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml")
+        return
+
+    config = Config.from_yaml(config_path)
+
+    # Check API key
+    if not config.llm.api_key or config.llm.api_key.startswith("YOUR_"):
+        print("❌ API key not configured in config.yaml")
+        return
+
+    # Create temporary workspace
+    with tempfile.TemporaryDirectory() as workspace_dir:
+        print(f"📁 Workspace: {workspace_dir}\n")
+
+        # Load system prompt (Agent will auto-inject workspace info)
+        system_prompt_path = Path("mini_agent/config/system_prompt.md")
+        if system_prompt_path.exists():
+            system_prompt = system_prompt_path.read_text(encoding="utf-8")
+        else:
+            system_prompt = "You are a helpful AI assistant that can use tools."
+
+        # Initialize LLM client
+        llm_client = LLMClient(
+            api_key=config.llm.api_key,
+            api_base=config.llm.api_base,
+            model=config.llm.model,
+        )
+
+        # Initialize tools
+        tools = [
+            ReadTool(workspace_dir=workspace_dir),
+            WriteTool(workspace_dir=workspace_dir),
+            EditTool(workspace_dir=workspace_dir),
+            BashTool(),
+        ]
+
+        # Create agent
+        agent = Agent(
+            llm_client=llm_client,
+            system_prompt=system_prompt,
+            tools=tools,
+            max_steps=10,
+            workspace_dir=workspace_dir,
+        )
+
+        # Task: Create a Python hello world file
+        task = """
+        Create a Python file named 'hello.py' that:
+        1. Defines a function called greet(name)
+        2. The function prints "Hello, {name}!"
+        3. Calls the function with name="Mini Agent"
+        """
+
+        print("📝 Task:")
+        print(task)
+        print("\n" + "=" * 60)
+        print("🤖 Agent is working...\n")
+
+        agent.add_user_message(task)
+
+        try:
+            result = await agent.run()
+
+            print("\n" + "=" * 60)
+            print("✅ Agent completed the task!")
+            print("=" * 60)
+            print(f"\nAgent's response:\n{result}\n")
+
+            # Check if file was created
+            hello_file = Path(workspace_dir) / "hello.py"
+            if hello_file.exists():
+                print("=" * 60)
+                print("📄 Created file content:")
+                print("=" * 60)
+                print(hello_file.read_text())
+                print("=" * 60)
+            else:
+                print("⚠️  File was not created (but agent may have completed differently)")
+
+        except Exception as e:
+            print(f"❌ Error: {e}")
+            import traceback
+
+            traceback.print_exc()
+
+
+async def demo_bash_task():
+    """Demo: Agent executes bash commands."""
+    print("\n" + "=" * 60)
+    print("Demo: Agent-Driven Bash Commands")
+    print("=" * 60)
+
+    # Load configuration
+    config_path = Path("mini_agent/config/config.yaml")
+    if not config_path.exists():
+        print("❌ config.yaml not found")
+        return
+
+    config = Config.from_yaml(config_path)
+
+    if not config.llm.api_key or config.llm.api_key.startswith("YOUR_"):
+        print("❌ API key not configured")
+        return
+
+    with tempfile.TemporaryDirectory() as workspace_dir:
+        print(f"📁 Workspace: {workspace_dir}\n")
+
+        # Load system prompt (Agent will auto-inject workspace info)
+        system_prompt_path = Path("mini_agent/config/system_prompt.md")
+        if system_prompt_path.exists():
+            system_prompt = system_prompt_path.read_text(encoding="utf-8")
+        else:
+            system_prompt = "You are a helpful AI assistant that can use tools."
+
+        # Initialize LLM
+        llm_client = LLMClient(
+            api_key=config.llm.api_key,
+            api_base=config.llm.api_base,
+            model=config.llm.model,
+        )
+
+        # Tools
+        tools = [
+            ReadTool(workspace_dir=workspace_dir),
+            WriteTool(workspace_dir=workspace_dir),
+            BashTool(),
+        ]
+
+        # Create agent
+        agent = Agent(
+            llm_client=llm_client,
+            system_prompt=system_prompt,
+            tools=tools,
+            max_steps=10,
+            workspace_dir=workspace_dir,
+        )
+
+        # Task: Use bash to get system info
+        task = """
+        Use bash commands to:
+        1. Show the current date and time
+        2. List all Python files in the current directory
+        3. Count how many Python files exist
+        """
+
+        print("📝 Task:")
+        print(task)
+        print("\n" + "=" * 60)
+        print("🤖 Agent is working...\n")
+
+        agent.add_user_message(task)
+
+        try:
+            result = await agent.run()
+
+            print("\n" + "=" * 60)
+            print("✅ Agent completed!")
+            print("=" * 60)
+            print(f"\nAgent's response:\n{result}\n")
+
+        except Exception as e:
+            print(f"❌ Error: {e}")
+
+
+async def main():
+    """Run all demos."""
+    print("=" * 60)
+    print("Simple Agent Usage Examples")
+    print("=" * 60)
+    print("\nThese examples show how to create an agent and give it tasks.")
+    print("The agent uses LLM to decide which tools to call.\n")
+
+    # Run demos
+    await demo_file_creation()
+    print("\n" * 2)
+    await demo_bash_task()
+
+    print("\n" + "=" * 60)
+    print("All demos completed! ✅")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/03_session_notes.py

@@ -0,0 +1,250 @@
+"""Example 3: Session Note Tool Usage
+
+This example demonstrates the Session Note Tool - one of the core features
+that allows agents to maintain memory across sessions.
+
+Based on: tests/test_note_tool.py, tests/test_integration.py
+"""
+
+import asyncio
+import json
+import tempfile
+from pathlib import Path
+
+from mini_agent import LLMClient
+from mini_agent.agent import Agent
+from mini_agent.config import Config
+from mini_agent.tools import BashTool, ReadTool, WriteTool
+from mini_agent.tools.note_tool import RecallNoteTool, SessionNoteTool
+
+
+async def demo_direct_note_usage():
+    """Demo: Direct usage of Session Note tools."""
+    print("\n" + "=" * 60)
+    print("Demo 1: Direct Session Note Tool Usage")
+    print("=" * 60)
+
+    with tempfile.NamedTemporaryFile(mode="w", delete=False, suffix=".json") as f:
+        note_file = f.name
+
+    try:
+        # Create tools
+        record_tool = SessionNoteTool(memory_file=note_file)
+        recall_tool = RecallNoteTool(memory_file=note_file)
+
+        # Record some notes
+        print("\n📝 Recording notes...")
+
+        result = await record_tool.execute(
+            content="User is a Python developer working on agent systems",
+            category="user_info",
+        )
+        print(f"  ✓ {result.content}")
+
+        result = await record_tool.execute(
+            content="Project name: mini-agent, Tech: Python 3.12 + async",
+            category="project_info",
+        )
+        print(f"  ✓ {result.content}")
+
+        result = await record_tool.execute(
+            content="User prefers concise, well-documented code",
+            category="user_preference",
+        )
+        print(f"  ✓ {result.content}")
+
+        # Recall all notes
+        print("\n🔍 Recalling all notes...")
+        result = await recall_tool.execute()
+        print(result.content)
+
+        # Recall filtered notes
+        print("\n🔍 Recalling user preferences only...")
+        result = await recall_tool.execute(category="user_preference")
+        print(result.content)
+
+        # Show the memory file
+        print("\n📄 Memory file content:")
+        print("=" * 60)
+        notes = json.loads(Path(note_file).read_text())
+        print(json.dumps(notes, indent=2, ensure_ascii=False))
+        print("=" * 60)
+
+    finally:
+        Path(note_file).unlink(missing_ok=True)
+
+
+async def demo_agent_with_notes():
+    """Demo: Agent using Session Notes to remember context."""
+    print("\n" + "=" * 60)
+    print("Demo 2: Agent with Session Memory")
+    print("=" * 60)
+
+    # Load configuration
+    config_path = Path("mini_agent/config/config.yaml")
+    if not config_path.exists():
+        print("❌ config.yaml not found")
+        return
+
+    config = Config.from_yaml(config_path)
+
+    if not config.llm.api_key or config.llm.api_key.startswith("YOUR_"):
+        print("❌ API key not configured")
+        return
+
+    with tempfile.TemporaryDirectory() as workspace_dir:
+        print(f"📁 Workspace: {workspace_dir}\n")
+
+        # Load system prompt (Agent will auto-inject workspace info)
+        system_prompt_path = Path("mini_agent/config/system_prompt.md")
+        if system_prompt_path.exists():
+            system_prompt = system_prompt_path.read_text(encoding="utf-8")
+        else:
+            system_prompt = "You are a helpful AI assistant."
+
+        # Add Session Note instructions
+        note_instructions = """
+
+IMPORTANT - Session Note Management:
+You have access to record_note and recall_notes tools. Use them to:
+- record_note: Save important facts, preferences, decisions that should persist
+- recall_notes: Retrieve previously saved notes
+
+Guidelines:
+- Proactively record key information during conversations
+- Recall notes at the start to restore context
+- Categories: user_info, user_preference, project_info, decision, etc.
+"""
+        system_prompt += note_instructions
+
+        # Initialize LLM
+        llm_client = LLMClient(
+            api_key=config.llm.api_key,
+            api_base=config.llm.api_base,
+            model=config.llm.model,
+        )
+
+        # Memory file
+        memory_file = Path(workspace_dir) / ".agent_memory.json"
+
+        # Tools including Session Note tools
+        tools = [
+            ReadTool(workspace_dir=workspace_dir),
+            WriteTool(workspace_dir=workspace_dir),
+            BashTool(),
+            SessionNoteTool(memory_file=str(memory_file)),
+            RecallNoteTool(memory_file=str(memory_file)),
+        ]
+
+        # === First Session ===
+        print("=" * 60)
+        print("Session 1: Teaching the agent about user preferences")
+        print("=" * 60)
+
+        agent1 = Agent(
+            llm_client=llm_client,
+            system_prompt=system_prompt,
+            tools=tools,
+            max_steps=15,
+            workspace_dir=workspace_dir,
+        )
+
+        task1 = """
+        Hello! Let me introduce myself:
+        - I'm Alex, a senior Python developer
+        - I'm building an AI agent framework called "mini-agent"
+        - I use Python 3.12 with asyncio
+        - I prefer type hints and comprehensive docstrings
+        - My coding style: clean, functional, well-tested
+
+        Please remember this information for future conversations.
+        Also, create a simple README.md file acknowledging you understood.
+        """
+
+        print(f"\n📝 User message:\n{task1}\n")
+        print("🤖 Agent is working...\n")
+
+        agent1.add_user_message(task1)
+
+        try:
+            result1 = await agent1.run()
+            print("\n" + "=" * 60)
+            print("Agent response:")
+            print("=" * 60)
+            print(result1)
+            print("=" * 60)
+
+            # Check memory file
+            if memory_file.exists():
+                notes = json.loads(memory_file.read_text())
+                print(f"\n✅ Agent recorded {len(notes)} notes in memory")
+                for note in notes:
+                    print(f"  - [{note['category']}] {note['content'][:50]}...")
+            else:
+                print("\n⚠️  No notes found")
+
+        except Exception as e:
+            print(f"❌ Error: {e}")
+            return
+
+        # === Second Session (New Agent Instance) ===
+        print("\n\n" + "=" * 60)
+        print("Session 2: New agent instance (simulating new conversation)")
+        print("=" * 60)
+
+        agent2 = Agent(
+            llm_client=llm_client,
+            system_prompt=system_prompt,
+            tools=tools,
+            max_steps=10,
+            workspace_dir=workspace_dir,
+        )
+
+        task2 = """
+        Hello! I'm back. Do you remember who I am and what project I'm working on?
+        What were my code style preferences?
+        """
+
+        print(f"\n📝 User message:\n{task2}\n")
+        print("🤖 Agent is working (should recall previous notes)...\n")
+
+        agent2.add_user_message(task2)
+
+        try:
+            result2 = await agent2.run()
+            print("\n" + "=" * 60)
+            print("Agent response:")
+            print("=" * 60)
+            print(result2)
+            print("=" * 60)
+
+            print("\n✅ Session Note Demo completed!")
+            print("\nKey Points:")
+            print("  1. Agent in Session 1 recorded important information")
+            print("  2. Agent in Session 2 recalled previous notes")
+            print("  3. Memory persists across agent instances via file")
+
+        except Exception as e:
+            print(f"❌ Error: {e}")
+
+
+async def main():
+    """Run all demos."""
+    print("=" * 60)
+    print("Session Note Tool Examples")
+    print("=" * 60)
+    print("\nSession Notes allow agents to remember context across sessions.")
+    print("This is a key feature for building production-ready agents.\n")
+
+    # Run demos
+    await demo_direct_note_usage()
+    print("\n" * 2)
+    await demo_agent_with_notes()
+
+    print("\n" + "=" * 60)
+    print("All demos completed! ✅")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/04_full_agent.py

@@ -0,0 +1,276 @@
+"""Example 4: Full Agent with All Features
+
+This example demonstrates a complete agent setup with:
+- All basic tools (Read, Write, Edit, Bash)
+- Session Note tools for memory
+- MCP tools (Memory, Search, etc.)
+- Skills integration
+
+Based on: tests/test_integration.py
+"""
+
+import asyncio
+import tempfile
+from pathlib import Path
+
+from mini_agent import LLMClient
+from mini_agent.agent import Agent
+from mini_agent.config import Config
+from mini_agent.tools import BashTool, EditTool, ReadTool, WriteTool
+from mini_agent.tools.mcp_loader import load_mcp_tools_async
+from mini_agent.tools.note_tool import RecallNoteTool, SessionNoteTool
+
+
+async def demo_full_agent():
+    """Demo: Full-featured agent with all capabilities."""
+    print("\n" + "=" * 60)
+    print("Full Mini Agent - All Features Enabled")
+    print("=" * 60)
+
+    # Load configuration
+    config_path = Path("mini_agent/config/config.yaml")
+    if not config_path.exists():
+        print("❌ config.yaml not found. Please run:")
+        print("   cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml")
+        return
+
+    config = Config.from_yaml(config_path)
+
+    # Check API key
+    if not config.llm.api_key or config.llm.api_key.startswith("YOUR_"):
+        print("❌ API key not configured in config.yaml")
+        return
+
+    # Create workspace
+    with tempfile.TemporaryDirectory() as workspace_dir:
+        print(f"📁 Workspace: {workspace_dir}")
+
+        # Load system prompt (Agent will auto-inject workspace info)
+        system_prompt_path = Path("mini_agent/config/system_prompt.md")
+        if system_prompt_path.exists():
+            system_prompt = system_prompt_path.read_text(encoding="utf-8")
+        else:
+            system_prompt = "You are a helpful AI assistant."
+
+        # Add Session Note instructions
+        note_instructions = """
+
+IMPORTANT - Session Memory:
+You have record_note and recall_notes tools. Use them to:
+- Save important facts, decisions, and context
+- Recall previous information across conversations
+"""
+        system_prompt += note_instructions
+
+        # Initialize LLM
+        llm_client = LLMClient(
+            api_key=config.llm.api_key,
+            api_base=config.llm.api_base,
+            model=config.llm.model,
+        )
+
+        # Initialize basic tools
+        tools = [
+            ReadTool(workspace_dir=workspace_dir),
+            WriteTool(workspace_dir=workspace_dir),
+            EditTool(workspace_dir=workspace_dir),
+            BashTool(),
+        ]
+        print("✓ Loaded 4 basic tools")
+
+        # Add Session Note tools
+        memory_file = Path(workspace_dir) / ".agent_memory.json"
+        tools.extend(
+            [
+                SessionNoteTool(memory_file=str(memory_file)),
+                RecallNoteTool(memory_file=str(memory_file)),
+            ]
+        )
+        print("✓ Loaded 2 Session Note tools")
+
+        # Load MCP tools (if configured)
+        try:
+            mcp_tools = await load_mcp_tools_async(config_path="mini_agent/config/mcp.json")
+            if mcp_tools:
+                tools.extend(mcp_tools)
+                print(f"✓ Loaded {len(mcp_tools)} MCP tools")
+            else:
+                print("⚠️  No MCP tools configured (mcp.json is empty or disabled)")
+        except Exception as e:
+            print(f"⚠️  MCP tools not loaded: {e}")
+
+        # Create agent
+        agent = Agent(
+            llm_client=llm_client,
+            system_prompt=system_prompt,
+            tools=tools,
+            max_steps=config.agent.max_steps,
+            workspace_dir=workspace_dir,
+        )
+
+        print(f"\n🤖 Agent created with {len(tools)} total tools\n")
+
+        # Task: Complex task that uses multiple tools
+        task = """
+        Please help me with the following tasks:
+
+        1. Create a Python script called 'calculator.py' that:
+           - Has functions for add, subtract, multiply, divide
+           - Has a main() function that demonstrates usage
+           - Includes proper docstrings and type hints
+
+        2. Create a README.md file that:
+           - Describes the calculator script
+           - Shows how to run it
+           - Lists the available functions
+
+        3. Test the calculator by running it with bash
+
+        4. Remember this project info:
+           - Project: Simple Calculator
+           - Language: Python
+           - Purpose: Demonstration of agent capabilities
+        """
+
+        print("=" * 60)
+        print("📝 Task:")
+        print("=" * 60)
+        print(task)
+        print("\n" + "=" * 60)
+        print("🤖 Agent is working...\n")
+
+        agent.add_user_message(task)
+
+        try:
+            result = await agent.run()
+
+            print("\n" + "=" * 60)
+            print("✅ Agent completed!")
+            print("=" * 60)
+            print(f"\nAgent's final response:\n{result}\n")
+
+            # Show created files
+            print("=" * 60)
+            print("��� Created files in workspace:")
+            print("=" * 60)
+
+            workspace = Path(workspace_dir)
+            for file in workspace.glob("*"):
+                if file.is_file() and not file.name.startswith("."):
+                    print(f"\n📄 {file.name}:")
+                    print("-" * 60)
+                    content = file.read_text()
+                    # Show first 20 lines
+                    lines = content.split("\n")[:20]
+                    print("\n".join(lines))
+                    if len(content.split("\n")) > 20:
+                        print("... (truncated)")
+                    print("-" * 60)
+
+            # Show memory
+            if memory_file.exists():
+                import json
+
+                notes = json.loads(memory_file.read_text())
+                print(f"\n💾 Session notes recorded: {len(notes)}")
+                for note in notes:
+                    print(f"  - [{note['category']}] {note['content'][:60]}...")
+
+        except Exception as e:
+            print(f"❌ Error during agent execution: {e}")
+            import traceback
+
+            traceback.print_exc()
+
+
+async def demo_interactive_mode():
+    """Demo: Interactive conversation with agent."""
+    print("\n" + "=" * 60)
+    print("Interactive Mini Agent")
+    print("=" * 60)
+    print("\nThis demo shows multi-turn conversation.")
+    print("(In production, use `mini-agent` for full interactive mode)")
+
+    # Load config
+    config_path = Path("mini_agent/config/config.yaml")
+    if not config_path.exists():
+        print("❌ config.yaml not found")
+        return
+
+    config = Config.from_yaml(config_path)
+
+    if not config.llm.api_key or config.llm.api_key.startswith("YOUR_"):
+        print("❌ API key not configured")
+        return
+
+    with tempfile.TemporaryDirectory() as workspace_dir:
+        # Setup
+        system_prompt = "You are a helpful assistant with access to tools."
+        llm_client = LLMClient(
+            api_key=config.llm.api_key,
+            api_base=config.llm.api_base,
+            model=config.llm.model,
+        )
+
+        tools = [
+            WriteTool(workspace_dir=workspace_dir),
+            ReadTool(workspace_dir=workspace_dir),
+            BashTool(),
+        ]
+
+        agent = Agent(
+            llm_client=llm_client,
+            system_prompt=system_prompt,
+            tools=tools,
+            max_steps=20,
+            workspace_dir=workspace_dir,
+        )
+
+        # Conversation turns
+        conversations = [
+            "Create a file called 'data.txt' with the numbers 1 to 5, one per line.",
+            "Now read the file and tell me what's in it.",
+            "Count how many lines are in the file using bash.",
+        ]
+
+        for i, message in enumerate(conversations, 1):
+            print(f"\n{'=' * 60}")
+            print(f"Turn {i}:")
+            print(f"{'=' * 60}")
+            print(f"User: {message}\n")
+
+            agent.add_user_message(message)
+
+            try:
+                result = await agent.run()
+                print(f"Agent: {result}\n")
+            except Exception as e:
+                print(f"Error: {e}")
+                break
+
+
+async def main():
+    """Run all demos."""
+    print("=" * 60)
+    print("Full Agent Examples")
+    print("=" * 60)
+    print("\nThese examples demonstrate the complete agent capabilities:")
+    print("- All basic tools (file operations, bash)")
+    print("- Session memory (persistent notes)")
+    print("- MCP tools (if configured)")
+    print("- Multi-turn conversations\n")
+
+    # Run demos
+    await demo_full_agent()
+    print("\n" * 2)
+    await demo_interactive_mode()
+
+    print("\n" + "=" * 60)
+    print("All demos completed! ✅")
+    print("=" * 60)
+    print("\n💡 Next step: Try the interactive mode with:")
+    print("   mini-agent\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/05_provider_selection.py

@@ -0,0 +1,190 @@
+"""Example: Using LLMClient with different providers.
+
+This example demonstrates how to use the LLMClient wrapper with different
+LLM providers (Anthropic or OpenAI) through the provider parameter.
+"""
+
+import asyncio
+import os
+from pathlib import Path
+
+import yaml
+
+from mini_agent import LLMClient, LLMProvider, Message
+
+
+async def demo_anthropic_provider():
+    """Demo using LLMClient with Anthropic provider."""
+    print("\n" + "=" * 60)
+    print("DEMO: LLMClient with Anthropic Provider")
+    print("=" * 60)
+
+    # Load config
+    config_path = Path("mini_agent/config/config.yaml")
+    with open(config_path, encoding="utf-8") as f:
+        config = yaml.safe_load(f)
+
+    # Initialize client with Anthropic provider
+    client = LLMClient(
+        api_key=config["api_key"],
+        provider=LLMProvider.ANTHROPIC,  # Specify Anthropic provider
+        model=config.get("model", "MiniMax-M2.1"),
+    )
+
+    print(f"Provider: {client.provider}")
+    print(f"API Base: {client.api_base}")
+
+    # Simple question
+    messages = [Message(role="user", content="Say 'Hello from Anthropic!'")]
+    print(f"\n👤 User: {messages[0].content}")
+
+    try:
+        response = await client.generate(messages)
+        if response.thinking:
+            print(f"💭 Thinking: {response.thinking}")
+        print(f"💬 Model: {response.content}")
+        print("✅ Anthropic provider demo completed")
+    except Exception as e:
+        print(f"❌ Error: {e}")
+
+
+async def demo_openai_provider():
+    """Demo using LLMClient with OpenAI provider."""
+    print("\n" + "=" * 60)
+    print("DEMO: LLMClient with OpenAI Provider")
+    print("=" * 60)
+
+    # Load config
+    config_path = Path("mini_agent/config/config.yaml")
+    with open(config_path, encoding="utf-8") as f:
+        config = yaml.safe_load(f)
+
+    # Initialize client with OpenAI provider
+    client = LLMClient(
+        api_key=config["api_key"],
+        provider=LLMProvider.OPENAI,  # Specify OpenAI provider
+        model=config.get("model", "MiniMax-M2.1"),
+    )
+
+    print(f"Provider: {client.provider}")
+    print(f"API Base: {client.api_base}")
+
+    # Simple question
+    messages = [Message(role="user", content="Say 'Hello from OpenAI!'")]
+    print(f"\n👤 User: {messages[0].content}")
+
+    try:
+        response = await client.generate(messages)
+        if response.thinking:
+            print(f"💭 Thinking: {response.thinking}")
+        print(f"💬 Model: {response.content}")
+        print("✅ OpenAI provider demo completed")
+    except Exception as e:
+        print(f"❌ Error: {e}")
+
+
+async def demo_default_provider():
+    """Demo using LLMClient with default provider."""
+    print("\n" + "=" * 60)
+    print("DEMO: LLMClient with Default Provider (Anthropic)")
+    print("=" * 60)
+
+    # Load config
+    config_path = Path("mini_agent/config/config.yaml")
+    with open(config_path, encoding="utf-8") as f:
+        config = yaml.safe_load(f)
+
+    # Initialize client without specifying provider (defaults to Anthropic)
+    client = LLMClient(
+        api_key=config["api_key"],
+        model=config.get("model", "MiniMax-M2.1"),
+    )
+
+    print(f"Provider (default): {client.provider}")
+    print(f"API Base: {client.api_base}")
+
+    # Simple question
+    messages = [Message(role="user", content="Say 'Hello with default provider!'")]
+    print(f"\n👤 User: {messages[0].content}")
+
+    try:
+        response = await client.generate(messages)
+        print(f"💬 Model: {response.content}")
+        print("✅ Default provider demo completed")
+    except Exception as e:
+        print(f"❌ Error: {e}")
+
+
+async def demo_provider_comparison():
+    """Compare responses from both providers."""
+    print("\n" + "=" * 60)
+    print("DEMO: Provider Comparison")
+    print("=" * 60)
+
+    # Load config
+    config_path = Path("mini_agent/config/config.yaml")
+    with open(config_path, encoding="utf-8") as f:
+        config = yaml.safe_load(f)
+
+    # Create clients for both providers
+    anthropic_client = LLMClient(
+        api_key=config["api_key"],
+        provider=LLMProvider.ANTHROPIC,
+        model=config.get("model", "MiniMax-M2.1"),
+    )
+
+    openai_client = LLMClient(
+        api_key=config["api_key"],
+        provider=LLMProvider.OPENAI,
+        model=config.get("model", "MiniMax-M2.1"),
+    )
+
+    # Same question for both
+    messages = [Message(role="user", content="What is 2+2?")]
+    print(f"\n👤 Question: {messages[0].content}\n")
+
+    try:
+        # Get response from Anthropic
+        anthropic_response = await anthropic_client.generate(messages)
+        print(f"🔵 Anthropic: {anthropic_response.content}")
+
+        # Get response from OpenAI
+        openai_response = await openai_client.generate(messages)
+        print(f"🟢 OpenAI: {openai_response.content}")
+
+        print("\n✅ Provider comparison completed")
+    except Exception as e:
+        print(f"❌ Error: {e}")
+
+
+async def main():
+    """Run all demos."""
+    print("\n🚀 LLM Provider Selection Demo")
+    print("This demo shows how to use LLMClient with different providers.")
+    print("Make sure you have configured API key in config.yaml.")
+
+    try:
+        # Demo default provider
+        await demo_default_provider()
+
+        # Demo Anthropic provider
+        await demo_anthropic_provider()
+
+        # Demo OpenAI provider
+        await demo_openai_provider()
+
+        # Demo provider comparison
+        await demo_provider_comparison()
+
+        print("\n✅ All demos completed successfully!")
+
+    except Exception as e:
+        print(f"\n❌ Error: {e}")
+        import traceback
+
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+

examples/06_tool_schema_demo.py

@@ -0,0 +1,285 @@
+"""Demo: Using Tool schemas with base Tool class.
+
+This example demonstrates how to use the Tool base class and its schema methods.
+"""
+
+import asyncio
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from mini_agent import LLMClient, LLMProvider
+from mini_agent.schema import Message
+from mini_agent.tools.base import Tool, ToolResult
+
+
+def load_config():
+    """Load config from config.yaml."""
+    config_path = Path("mini_agent/config/config.yaml")
+    with open(config_path, encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+class WeatherTool(Tool):
+    """Example weather tool."""
+
+    @property
+    def name(self) -> str:
+        return "get_weather"
+
+    @property
+    def description(self) -> str:
+        return "Get current weather information for a location. Returns temperature and conditions."
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "location": {
+                    "type": "string",
+                    "description": "City and state, e.g. 'San Francisco, CA' or 'London, UK'",
+                },
+                "unit": {
+                    "type": "string",
+                    "enum": ["celsius", "fahrenheit"],
+                    "description": "Temperature unit (celsius or fahrenheit)",
+                },
+            },
+            "required": ["location"],
+        }
+
+    async def execute(self, **kwargs) -> ToolResult:
+        """Mock execute method."""
+        return ToolResult(success=True, content="Weather data")
+
+
+class SearchTool(Tool):
+    """Example search tool."""
+
+    @property
+    def name(self) -> str:
+        return "search_web"
+
+    @property
+    def description(self) -> str:
+        return "Search the web for information about a topic"
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Search query string",
+                },
+                "max_results": {
+                    "type": "integer",
+                    "description": "Maximum number of results to return (1-10)",
+                },
+            },
+            "required": ["query"],
+        }
+
+    async def execute(self, **kwargs) -> ToolResult:
+        """Mock execute method."""
+        return ToolResult(success=True, content="Search results")
+
+
+class CalculatorTool(Tool):
+    """Example calculator tool."""
+
+    @property
+    def name(self) -> str:
+        return "calculator"
+
+    @property
+    def description(self) -> str:
+        return "Perform arithmetic calculations"
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "expression": {
+                    "type": "string",
+                    "description": "Mathematical expression to evaluate, e.g. '2 + 2' or '10 * 5'",
+                }
+            },
+            "required": ["expression"],
+        }
+
+    async def execute(self, **kwargs) -> ToolResult:
+        """Mock execute method."""
+        return ToolResult(success=True, content="Calculation result")
+
+
+class TranslateTool(Tool):
+    """Example translate tool."""
+
+    @property
+    def name(self) -> str:
+        return "translate"
+
+    @property
+    def description(self) -> str:
+        return "Translate text from one language to another"
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "text": {
+                    "type": "string",
+                    "description": "Text to translate",
+                },
+                "target_language": {
+                    "type": "string",
+                    "description": "Target language code (e.g. 'en', 'es', 'fr')",
+                },
+            },
+            "required": ["text", "target_language"],
+        }
+
+    async def execute(self, **kwargs) -> ToolResult:
+        """Mock execute method."""
+        return ToolResult(success=True, content="Translation result")
+
+
+async def demo_tool_schemas():
+    """Demonstrate using Tool objects with LLM."""
+    config = load_config()
+
+    print("=" * 60)
+    print("Method 1: Using Tool Objects with LLM")
+    print("=" * 60)
+
+    # Create tool instances
+    weather_tool = WeatherTool()
+    search_tool = SearchTool()
+
+    # Create client
+    client = LLMClient(
+        api_key=config["api_key"],
+        provider=LLMProvider.ANTHROPIC,
+        model="MiniMax-M2.1",
+    )
+
+    # Test with a query that should trigger weather tool
+    messages = [
+        Message(
+            role="user",
+            content="What's the weather like in Tokyo? I want it in celsius.",
+        )
+    ]
+
+    print("\nQuery: What's the weather like in Tokyo? I want it in celsius.")
+    print("\nAvailable tools:")
+    print(f"  1. {weather_tool.name}: {weather_tool.description}")
+    print(f"  2. {search_tool.name}: {search_tool.description}")
+
+    # Pass Tool objects directly to generate
+    response = await client.generate(
+        messages,
+        tools=[weather_tool, search_tool],  # Using Tool objects
+    )
+
+    print(f"\nResponse content: {response.content}")
+
+    if response.thinking:
+        print(f"\nThinking: {response.thinking}")
+
+    if response.tool_calls:
+        print(f"\nTool calls made: {len(response.tool_calls)}")
+        for tool_call in response.tool_calls:
+            print(f"  - Function: {tool_call.function.name}")
+            print(f"    Arguments: {tool_call.function.arguments}")
+
+
+async def demo_multiple_tools():
+    """Demonstrate using multiple Tool instances."""
+    config = load_config()
+
+    print("\n" + "=" * 60)
+    print("Method 2: Using Multiple Tool Instances")
+    print("=" * 60)
+
+    # Create tool instances
+    calculator_tool = CalculatorTool()
+    translate_tool = TranslateTool()
+
+    client = LLMClient(
+        api_key=config["api_key"],
+        provider=LLMProvider.ANTHROPIC,
+        model="MiniMax-M2.1",
+    )
+
+    messages = [Message(role="user", content="Calculate 15 * 23 for me")]
+
+    print("\nQuery: Calculate 15 * 23 for me")
+    print("\nAvailable tools:")
+    print("  1. calculator (Tool)")
+    print("  2. translate (Tool)")
+
+    response = await client.generate(messages, tools=[calculator_tool, translate_tool])
+
+    print(f"\nResponse content: {response.content}")
+
+    if response.thinking:
+        print(f"\nThinking: {response.thinking}")
+
+    if response.tool_calls:
+        print(f"\nTool calls made: {len(response.tool_calls)}")
+        for tool_call in response.tool_calls:
+            print(f"  - Function: {tool_call.function.name}")
+            print(f"    Arguments: {tool_call.function.arguments}")
+
+
+async def demo_tool_schema_methods():
+    """Demonstrate Tool schema conversion methods."""
+    print("\n" + "=" * 60)
+    print("Method 3: Tool Schema Conversion Methods")
+    print("=" * 60)
+
+    weather_tool = WeatherTool()
+
+    print("\nTool to Anthropic schema (to_schema):")
+    anthropic_schema = weather_tool.to_schema()
+    print(f"  {anthropic_schema}")
+
+    print("\nTool to OpenAI schema (to_openai_schema):")
+    openai_schema = weather_tool.to_openai_schema()
+    print(f"  {openai_schema}")
+
+    print("\nSchema methods allow flexible tool usage with different LLM providers.")
+
+
+async def main():
+    """Run all demos."""
+    print("\n🚀 Tool Schema Demo - Using Tool Base Class\n")
+
+    try:
+        # Demo 1: Tool objects with LLM
+        await demo_tool_schemas()
+
+        # Demo 2: Multiple tools
+        await demo_multiple_tools()
+
+        # Demo 3: Schema methods
+        await demo_tool_schema_methods()
+
+        print("\n✅ All demos completed successfully!")
+
+    except Exception as e:
+        print(f"\n❌ Error: {e}")
+        import traceback
+
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/README.md

@@ -0,0 +1,219 @@
+# Mini Agent Examples
+
+This directory contains a series of progressive examples to help you understand how to use the Mini Agent framework.
+
+## 📚 Example List
+
+### 01_basic_tools.py - Basic Tool Usage
+
+**Difficulty**: ⭐ Beginner
+
+**Content**:
+- How to directly use ReadTool, WriteTool, EditTool, BashTool
+- No Agent or LLM involved, pure tool call demonstrations
+- Perfect for understanding each tool's basic functionality
+
+**Run**:
+```bash
+python examples/01_basic_tools.py
+```
+
+**Key Learnings**:
+- Tool input parameter formats
+- ToolResult return structure
+- Error handling approaches
+
+---
+
+### 02_simple_agent.py - Simple Agent Usage
+
+**Difficulty**: ⭐⭐ Beginner-Intermediate
+
+**Content**:
+- Create the simplest Agent
+- Have Agent perform file creation tasks
+- Have Agent execute bash command tasks
+- Understand Agent execution flow
+
+**Run**:
+```bash
+# Requires API key configuration first
+python examples/02_simple_agent.py
+```
+
+**Key Learnings**:
+- Agent initialization process
+- How to give tasks to Agent
+- How Agent autonomously selects tools
+- Task completion criteria
+
+**Prerequisites**:
+- API key configured in `mini_agent/config/config.yaml`
+
+---
+
+### 03_session_notes.py - Session Note Tool
+
+**Difficulty**: ⭐⭐⭐ Intermediate
+
+**Content**:
+- Direct usage of Session Note tools (record_note, recall_notes)
+- Agent using Session Notes to maintain cross-session memory
+- Demonstrate how two Agent instances share memory
+
+**Run**:
+```bash
+python examples/03_session_notes.py
+```
+
+**Key Learnings**:
+- How Session Notes work
+- Note categorization management (category)
+- How to guide Agent to use notes in system prompt
+- Cross-session memory implementation
+
+**Highlight**:
+This is one of the core features of this project! Shows a lightweight but effective session memory management solution.
+
+---
+
+### 04_full_agent.py - Full-Featured Agent
+
+**Difficulty**: ⭐⭐⭐⭐ Advanced
+
+**Content**:
+- Complete Agent setup with all features
+- Integration of basic tools + Session Notes + MCP tools
+- Full execution flow for complex tasks
+- Multi-turn conversation examples
+
+**Run**:
+```bash
+python examples/04_full_agent.py
+```
+
+**Key Learnings**:
+- How to combine multiple tools
+- MCP tool loading and usage
+- Complex task decomposition and execution
+- Production environment Agent configuration
+
+**Prerequisites**:
+- API key configured
+- (Optional) MCP tools configured
+
+---
+
+## 🚀 Quick Start
+
+### 1. Configure API Key
+
+```bash
+# Copy configuration template
+cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml
+
+# Edit config file and fill in your MiniMax API Key
+vim mini_agent/config/config.yaml
+```
+
+### 2. Run Your First Example
+
+```bash
+# Example that doesn't need API key
+python examples/01_basic_tools.py
+
+# Example that needs API key
+python examples/02_simple_agent.py
+```
+
+### 3. Progressive Learning
+
+Recommended to learn in numerical order:
+1. **01_basic_tools.py** - Understand tools
+2. **02_simple_agent.py** - Understand Agent
+3. **03_session_notes.py** - Understand memory management
+4. **04_full_agent.py** - Understand complete system
+
+---
+
+## 📖 Relationship with Test Cases
+
+These examples are all refined from test cases in the `tests/` directory:
+
+| Example             | Based on Test                                        | Description                     |
+| ------------------- | ---------------------------------------------------- | ------------------------------- |
+| 01_basic_tools.py   | tests/test_tools.py                                  | Basic tool unit tests           |
+| 02_simple_agent.py  | tests/test_agent.py                                  | Agent basic functionality tests |
+| 03_session_notes.py | tests/test_note_tool.py<br>tests/test_integration.py | Session Note tool tests         |
+| 04_full_agent.py    | tests/test_integration.py                            | Complete integration tests      |
+
+---
+
+## 💡 Recommended Learning Paths
+
+### Path 1: Quick Start
+1. Run `01_basic_tools.py` - Learn about tools
+2. Run `02_simple_agent.py` - Run your first Agent
+3. Go directly to interactive mode with `mini-agent`
+
+### Path 2: Deep Understanding
+1. Read and run all examples (01 → 04)
+2. Read corresponding test cases (`tests/`)
+3. Read core implementation code (`mini_agent/`)
+4. Try modifying examples to implement your own features
+
+### Path 3: Production Application
+1. Understand all examples
+2. Read [Production Deployment Guide](../docs/PRODUCTION_GUIDE.md)
+3. Configure MCP tools and Skills
+4. Extend tool set based on needs
+
+---
+
+## 🔧 Troubleshooting
+
+### API Key Error
+```
+❌ API key not configured in config.yaml
+```
+**Solution**: Ensure you've configured a valid MiniMax API Key in `mini_agent/config/config.yaml`
+
+### config.yaml Not Found
+```
+❌ config.yaml not found
+```
+**Solution**:
+```bash
+cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml
+```
+
+### MCP Tools Loading Failed
+```
+⚠️ MCP tools not loaded: [error message]
+```
+**Solution**: MCP tools are optional and don't affect basic functionality. If you need them, refer to the MCP configuration section in the main README.
+
+---
+
+## 📚 More Resources
+
+- [Main Project README](../README.md) - Complete project documentation
+- [Test Cases](../tests/) - More usage examples
+- [Core Implementation](../mini_agent/) - Source code
+- [Production Guide](../docs/PRODUCTION_GUIDE.md) - Deployment guide
+
+---
+
+## 🤝 Contributing Examples
+
+If you have good usage examples, PRs are welcome!
+
+Suggested new example directions:
+- Web search integration examples (using MiniMax Search MCP)
+- Skills usage examples (document processing, design, etc.)
+- Custom tool development examples
+- Error handling and retry mechanism examples
+
+---
+
+**⭐ If these examples help you, please give the project a Star!**

examples/README_CN.md

@@ -0,0 +1,219 @@
+# Mini Agent Examples
+
+这个目录包含了一系列渐进式的示例，帮助你理解如何使用 Mini Agent 框架。
+
+## 📚 示例列表
+
+### 01_basic_tools.py - 基础工具使用
+
+**难度**: ⭐ 入门
+
+**内容**:
+- 如何直接使用 ReadTool、WriteTool、EditTool、BashTool
+- 不涉及 Agent 或 LLM，纯粹的工具调用演示
+- 适合理解每个工具的基本功能
+
+**运行**:
+```bash
+python examples/01_basic_tools.py
+```
+
+**学习要点**:
+- 工具的输入参数格式
+- ToolResult 的返回结构
+- 错误处理方式
+
+---
+
+### 02_simple_agent.py - 简单 Agent 使用
+
+**难度**: ⭐⭐ 初级
+
+**内容**:
+- 创建最简单的 Agent
+- 让 Agent 执行文件创建任务
+- 让 Agent 执行 bash 命令任务
+- 理解 Agent 的执行流程
+
+**运行**:
+```bash
+# 需要先配置 API key
+python examples/02_simple_agent.py
+```
+
+**学习要点**:
+- Agent 的初始化流程
+- 如何给 Agent 下达任务
+- Agent 如何自主选择工具
+- 任务完成的判断标准
+
+**前置要求**:
+- 已配置 `mini_agent/config/config.yaml` 中的 API key
+
+---
+
+### 03_session_notes.py - Session Note 工具
+
+**难度**: ⭐⭐⭐ 中级
+
+**内容**:
+- 直接使用 Session Note 工具（record_note, recall_notes）
+- Agent 使用 Session Note 保持跨会话记忆
+- 演示两个 Agent 实例如何共享记忆
+
+**运行**:
+```bash
+python examples/03_session_notes.py
+```
+
+**学习要点**:
+- Session Note 的工作原理
+- 笔记的分类管理（category）
+- 如何在 system prompt 中引导 Agent 使用笔记
+- 跨会话记忆的实现方式
+
+**亮点**:
+这是本项目的核心特性之一！展示了一种轻量但有效的会话记忆管理方案。
+
+---
+
+### 04_full_agent.py - 完整功能 Agent
+
+**难度**: ⭐⭐⭐⭐ 高级
+
+**内容**:
+- 包含所有功能的完整 Agent 设置
+- 集成基础工具 + Session Notes + MCP 工具
+- 复杂任务的完整执行流程
+- 多轮对话示例
+
+**运行**:
+```bash
+python examples/04_full_agent.py
+```
+
+**学习要点**:
+- 如何组合多种工具
+- MCP 工具的加载和使用
+- 复杂任务的分解和执行
+- 生产环境的 Agent 配置
+
+**前置要求**:
+- 已配置 API key
+- （可选）配置了 MCP 工具
+
+---
+
+## 🚀 快速开始
+
+### 1. 配置 API Key
+
+```bash
+# 复制配置模板
+cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml
+
+# 编辑配置文件，填入你的 MiniMax API Key
+vim mini_agent/config/config.yaml
+```
+
+### 2. 运行第一个示例
+
+```bash
+# 不需要 API key 的示例
+python examples/01_basic_tools.py
+
+# 需要 API key 的示例
+python examples/02_simple_agent.py
+```
+
+### 3. 逐步学习
+
+建议按照编号顺序学习：
+1. **01_basic_tools.py** - 理解工具
+2. **02_simple_agent.py** - 理解 Agent
+3. **03_session_notes.py** - 理解记忆管理
+4. **04_full_agent.py** - 理解完整系统
+
+---
+
+## 📖 与测试用例的对应关系
+
+这些示例都是基于 `tests/` 目录中的测试用例提炼而来：
+
+| Example             | Based on Test                                        | Description           |
+| ------------------- | ---------------------------------------------------- | --------------------- |
+| 01_basic_tools.py   | tests/test_tools.py                                  | 基础工具单元测试      |
+| 02_simple_agent.py  | tests/test_agent.py                                  | Agent 基本功能测试    |
+| 03_session_notes.py | tests/test_note_tool.py<br>tests/test_integration.py | Session Note 工具测试 |
+| 04_full_agent.py    | tests/test_integration.py                            | 完整集成测试          |
+
+---
+
+## 💡 学习路径建议
+
+### 路径 1: 快速上手
+1. 运行 `01_basic_tools.py` - 了解工具
+2. 运行 `02_simple_agent.py` - 运行第一个 Agent
+3. 直接使用 `mini-agent` 进入交互模式
+
+### 路径 2: 深入理解
+1. 阅读并运行所有示例 (01 → 04)
+2. 阅读对应的测试用例 (`tests/`)
+3. 阅读核心实现代码 (`mini_agent/`)
+4. 尝试修改示例，实现自己的功能
+
+### 路径 3: 生产应用
+1. 理解所有示例
+2. 阅读 [生产环境部署指南](../docs/PRODUCTION_GUIDE.md)
+3. 配置 MCP 工具和 Skills
+4. 根据需求扩展工具集
+
+---
+
+## 🔧 故障排除
+
+### API Key 错误
+```
+❌ API key not configured in config.yaml
+```
+**解决**: 确保在 `mini_agent/config/config.yaml` 中配置了有效的 MiniMax API Key
+
+### 找不到 config.yaml
+```
+❌ config.yaml not found
+```
+**解决**:
+```bash
+cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml
+```
+
+### MCP 工具加载失败
+```
+⚠️ MCP tools not loaded: [error message]
+```
+**解决**: MCP 工具是可选的，不影响基本功能。如需使用，请参考主 README 中的 MCP 配置章节。
+
+---
+
+## 📚 更多资源
+
+- [项目主 README](../README.md) - 完整项目文档
+- [测试用例](../tests/) - 更多使用示例
+- [核心实现](../mini_agent/) - 源代码
+- [生产环境指南](../docs/PRODUCTION_GUIDE.md) - 部署指南
+
+---
+
+## 🤝 贡献示例
+
+如果你有好的使用示例，欢迎提交 PR！
+
+建议的新示例方向：
+- Web 搜索集成示例（使用 MiniMax Search MCP）
+- Skills 使用示例（文档处理、设计等）
+- 自定义工具开发示例
+- 错误处理和重试机制示例
+
+---
+
+**⭐ 如果这些示例对你有帮助，欢迎给项目一个 Star！**

mini_agent/__init__.py

@@ -0,0 +1,17 @@
+"""Mini Agent - Minimal single agent with basic tools and MCP support."""
+
+from .agent import Agent
+from .llm import LLMClient
+from .schema import FunctionCall, LLMProvider, LLMResponse, Message, ToolCall
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Agent",
+    "LLMClient",
+    "LLMProvider",
+    "Message",
+    "LLMResponse",
+    "ToolCall",
+    "FunctionCall",
+]

mini_agent/acp/__init__.py

@@ -0,0 +1,197 @@
+"""ACP (Agent Client Protocol) bridge for Mini-Agent."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from acp import (
+    PROTOCOL_VERSION,
+    AgentSideConnection,
+    CancelNotification,
+    InitializeRequest,
+    InitializeResponse,
+    NewSessionRequest,
+    NewSessionResponse,
+    PromptRequest,
+    PromptResponse,
+    session_notification,
+    start_tool_call,
+    stdio_streams,
+    text_block,
+    tool_content,
+    update_agent_message,
+    update_agent_thought,
+    update_tool_call,
+)
+from pydantic import field_validator
+from acp.schema import AgentCapabilities, Implementation, McpCapabilities
+
+from mini_agent.agent import Agent
+from mini_agent.cli import add_workspace_tools, initialize_base_tools
+from mini_agent.config import Config
+from mini_agent.llm import LLMClient
+from mini_agent.retry import RetryConfig as RetryConfigBase
+from mini_agent.schema import Message
+
+logger = logging.getLogger(__name__)
+
+
+try:
+    class InitializeRequestPatch(InitializeRequest):
+        @field_validator("protocolVersion", mode="before")
+        @classmethod
+        def normalize_protocol_version(cls, value: Any) -> int:
+            if isinstance(value, str):
+                try:
+                    return int(value.split(".")[0])
+                except Exception:
+                    return 1
+            if isinstance(value, (int, float)):
+                return int(value)
+            return 1
+
+    InitializeRequest = InitializeRequestPatch
+    InitializeRequest.model_rebuild(force=True)
+except Exception:  # pragma: no cover - defensive
+    logger.debug("ACP schema patch skipped")
+
+
+@dataclass
+class SessionState:
+    agent: Agent
+    cancelled: bool = False
+
+
+class MiniMaxACPAgent:
+    """Minimal ACP adapter wrapping the existing Agent runtime."""
+
+    def __init__(
+        self,
+        conn: AgentSideConnection,
+        config: Config,
+        llm: LLMClient,
+        base_tools: list,
+        system_prompt: str,
+    ):
+        self._conn = conn
+        self._config = config
+        self._llm = llm
+        self._base_tools = base_tools
+        self._system_prompt = system_prompt
+        self._sessions: dict[str, SessionState] = {}
+
+    async def initialize(self, params: InitializeRequest) -> InitializeResponse:  # noqa: ARG002
+        return InitializeResponse(
+            protocolVersion=PROTOCOL_VERSION,
+            agentCapabilities=AgentCapabilities(loadSession=False),
+            agentInfo=Implementation(name="mini-agent", title="Mini-Agent", version="0.1.0"),
+        )
+
+    async def newSession(self, params: NewSessionRequest) -> NewSessionResponse:
+        session_id = f"sess-{len(self._sessions)}-{uuid4().hex[:8]}"
+        workspace = Path(params.cwd or self._config.agent.workspace_dir).expanduser()
+        if not workspace.is_absolute():
+            workspace = workspace.resolve()
+        tools = list(self._base_tools)
+        add_workspace_tools(tools, self._config, workspace)
+        agent = Agent(llm_client=self._llm, system_prompt=self._system_prompt, tools=tools, max_steps=self._config.agent.max_steps, workspace_dir=str(workspace))
+        self._sessions[session_id] = SessionState(agent=agent)
+        return NewSessionResponse(sessionId=session_id)
+
+    async def prompt(self, params: PromptRequest) -> PromptResponse:
+        state = self._sessions.get(params.sessionId)
+        if not state:
+            # Auto-create session if not found (compatibility with clients that skip newSession)
+            logger.warning(f"Session '{params.sessionId}' not found, auto-creating new session")
+            new_session = await self.newSession(NewSessionRequest(cwd=None))
+            state = self._sessions.get(new_session.sessionId)
+            if not state:
+                logger.error("Failed to auto-create session")
+                return PromptResponse(stopReason="refusal")
+        state.cancelled = False
+        user_text = "\n".join(block.get("text", "") if isinstance(block, dict) else getattr(block, "text", "") for block in params.prompt)
+        state.agent.messages.append(Message(role="user", content=user_text))
+        stop_reason = await self._run_turn(state, params.sessionId)
+        return PromptResponse(stopReason=stop_reason)
+
+    async def cancel(self, params: CancelNotification) -> None:
+        state = self._sessions.get(params.sessionId)
+        if state:
+            state.cancelled = True
+
+    async def _run_turn(self, state: SessionState, session_id: str) -> str:
+        agent = state.agent
+        for _ in range(agent.max_steps):
+            if state.cancelled:
+                return "cancelled"
+            tool_schemas = [tool.to_schema() for tool in agent.tools.values()]
+            try:
+                response = await agent.llm.generate(messages=agent.messages, tools=tool_schemas)
+            except Exception as exc:
+                logger.exception("LLM error")
+                await self._send(session_id, update_agent_message(text_block(f"Error: {exc}")))
+                return "refusal"
+            if response.thinking:
+                await self._send(session_id, update_agent_thought(text_block(response.thinking)))
+            if response.content:
+                await self._send(session_id, update_agent_message(text_block(response.content)))
+            agent.messages.append(Message(role="assistant", content=response.content, thinking=response.thinking, tool_calls=response.tool_calls))
+            if not response.tool_calls:
+                return "end_turn"
+            for call in response.tool_calls:
+                name, args = call.function.name, call.function.arguments
+                # Show tool name with key arguments for better visibility
+                args_preview = ", ".join(f"{k}={repr(v)[:50]}" for k, v in list(args.items())[:2]) if isinstance(args, dict) else ""
+                label = f"🔧 {name}({args_preview})" if args_preview else f"🔧 {name}()"
+                await self._send(session_id, start_tool_call(call.id, label, kind="execute", raw_input=args))
+                tool = agent.tools.get(name)
+                if not tool:
+                    text, status = f"❌ Unknown tool: {name}", "failed"
+                else:
+                    try:
+                        result = await tool.execute(**args)
+                        status = "completed" if result.success else "failed"
+                        prefix = "✅" if result.success else "❌"
+                        text = f"{prefix} {result.content if result.success else result.error or 'Tool execution failed'}"
+                    except Exception as exc:
+                        status, text = "failed", f"❌ Tool error: {exc}"
+                await self._send(session_id, update_tool_call(call.id, status=status, content=[tool_content(text_block(text))], raw_output=text))
+                agent.messages.append(Message(role="tool", content=text, tool_call_id=call.id, name=name))
+        return "max_turn_requests"
+
+    async def _send(self, session_id: str, update: Any) -> None:
+        await self._conn.sessionUpdate(session_notification(session_id, update))
+
+
+async def run_acp_server(config: Config | None = None) -> None:
+    """Run Mini-Agent as an ACP-compatible stdio server."""
+    config = config or Config.load()
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(name)s: %(message)s")
+    base_tools, skill_loader = await initialize_base_tools(config)
+    prompt_path = Config.find_config_file(config.agent.system_prompt_path)
+    if prompt_path and prompt_path.exists():
+        system_prompt = prompt_path.read_text(encoding="utf-8")
+    else:
+        system_prompt = "You are a helpful AI assistant."
+    if skill_loader:
+        meta = skill_loader.get_skills_metadata_prompt()
+        if meta:
+            system_prompt = f"{system_prompt.rstrip()}\n\n{meta}"
+    rcfg = config.llm.retry
+    llm = LLMClient(api_key=config.llm.api_key, api_base=config.llm.api_base, model=config.llm.model, retry_config=RetryConfigBase(enabled=rcfg.enabled, max_retries=rcfg.max_retries, initial_delay=rcfg.initial_delay, max_delay=rcfg.max_delay, exponential_base=rcfg.exponential_base))
+    reader, writer = await stdio_streams()
+    AgentSideConnection(lambda conn: MiniMaxACPAgent(conn, config, llm, base_tools, system_prompt), writer, reader)
+    logger.info("Mini-Agent ACP server running")
+    await asyncio.Event().wait()
+
+
+def main() -> None:
+    asyncio.run(run_acp_server())
+
+
+__all__ = ["MiniMaxACPAgent", "run_acp_server", "main"]

mini_agent/acp/server.py

@@ -0,0 +1,6 @@
+"""ACP server entry point."""
+
+from mini_agent.acp import main
+
+if __name__ == "__main__":
+    main()

mini_agent/agent.py

@@ -0,0 +1,523 @@
+"""Core Agent implementation."""
+
+import asyncio
+import json
+from pathlib import Path
+from time import perf_counter
+from typing import Optional
+
+import tiktoken
+
+from .llm import LLMClient
+from .logger import AgentLogger
+from .schema import Message
+from .tools.base import Tool, ToolResult
+from .utils import calculate_display_width
+
+
+# ANSI color codes
+class Colors:
+    """Terminal color definitions"""
+
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+
+    # Foreground colors
+    RED = "\033[31m"
+    GREEN = "\033[32m"
+    YELLOW = "\033[33m"
+    BLUE = "\033[34m"
+    MAGENTA = "\033[35m"
+    CYAN = "\033[36m"
+
+    # Bright colors
+    BRIGHT_BLACK = "\033[90m"
+    BRIGHT_RED = "\033[91m"
+    BRIGHT_GREEN = "\033[92m"
+    BRIGHT_YELLOW = "\033[93m"
+    BRIGHT_BLUE = "\033[94m"
+    BRIGHT_MAGENTA = "\033[95m"
+    BRIGHT_CYAN = "\033[96m"
+    BRIGHT_WHITE = "\033[97m"
+
+
+class Agent:
+    """Single agent with basic tools and MCP support."""
+
+    def __init__(
+        self,
+        llm_client: LLMClient,
+        system_prompt: str,
+        tools: list[Tool],
+        max_steps: int = 50,
+        workspace_dir: str = "./workspace",
+        token_limit: int = 80000,  # Summary triggered when tokens exceed this value
+    ):
+        self.llm = llm_client
+        self.tools = {tool.name: tool for tool in tools}
+        self.max_steps = max_steps
+        self.token_limit = token_limit
+        self.workspace_dir = Path(workspace_dir)
+        # Cancellation event for interrupting agent execution (set externally, e.g., by Esc key)
+        self.cancel_event: Optional[asyncio.Event] = None
+
+        # Ensure workspace exists
+        self.workspace_dir.mkdir(parents=True, exist_ok=True)
+
+        # Inject workspace information into system prompt if not already present
+        if "Current Workspace" not in system_prompt:
+            workspace_info = f"\n\n## Current Workspace\nYou are currently working in: `{self.workspace_dir.absolute()}`\nAll relative paths will be resolved relative to this directory."
+            system_prompt = system_prompt + workspace_info
+
+        self.system_prompt = system_prompt
+
+        # Initialize message history
+        self.messages: list[Message] = [Message(role="system", content=system_prompt)]
+
+        # Initialize logger
+        self.logger = AgentLogger()
+
+        # Token usage from last API response (updated after each LLM call)
+        self.api_total_tokens: int = 0
+        # Flag to skip token check right after summary (avoid consecutive triggers)
+        self._skip_next_token_check: bool = False
+
+    def add_user_message(self, content: str):
+        """Add a user message to history."""
+        self.messages.append(Message(role="user", content=content))
+
+    def _check_cancelled(self) -> bool:
+        """Check if agent execution has been cancelled.
+
+        Returns:
+            True if cancelled, False otherwise.
+        """
+        if self.cancel_event is not None and self.cancel_event.is_set():
+            return True
+        return False
+
+    def _cleanup_incomplete_messages(self):
+        """Remove the incomplete assistant message and its partial tool results.
+
+        This ensures message consistency after cancellation by removing
+        only the current step's incomplete messages, preserving completed steps.
+        """
+        # Find the index of the last assistant message
+        last_assistant_idx = -1
+        for i in range(len(self.messages) - 1, -1, -1):
+            if self.messages[i].role == "assistant":
+                last_assistant_idx = i
+                break
+
+        if last_assistant_idx == -1:
+            # No assistant message found, nothing to clean
+            return
+
+        # Remove the last assistant message and all tool results after it
+        removed_count = len(self.messages) - last_assistant_idx
+        if removed_count > 0:
+            self.messages = self.messages[:last_assistant_idx]
+            print(f"{Colors.DIM}   Cleaned up {removed_count} incomplete message(s){Colors.RESET}")
+
+    def _estimate_tokens(self) -> int:
+        """Accurately calculate token count for message history using tiktoken
+
+        Uses cl100k_base encoder (GPT-4/Claude/M2 compatible)
+        """
+        try:
+            # Use cl100k_base encoder (used by GPT-4 and most modern models)
+            encoding = tiktoken.get_encoding("cl100k_base")
+        except Exception:
+            # Fallback: if tiktoken initialization fails, use simple estimation
+            return self._estimate_tokens_fallback()
+
+        total_tokens = 0
+
+        for msg in self.messages:
+            # Count text content
+            if isinstance(msg.content, str):
+                total_tokens += len(encoding.encode(msg.content))
+            elif isinstance(msg.content, list):
+                for block in msg.content:
+                    if isinstance(block, dict):
+                        # Convert dict to string for calculation
+                        total_tokens += len(encoding.encode(str(block)))
+
+            # Count thinking
+            if msg.thinking:
+                total_tokens += len(encoding.encode(msg.thinking))
+
+            # Count tool_calls
+            if msg.tool_calls:
+                total_tokens += len(encoding.encode(str(msg.tool_calls)))
+
+            # Metadata overhead per message (approximately 4 tokens)
+            total_tokens += 4
+
+        return total_tokens
+
+    def _estimate_tokens_fallback(self) -> int:
+        """Fallback token estimation method (when tiktoken is unavailable)"""
+        total_chars = 0
+        for msg in self.messages:
+            if isinstance(msg.content, str):
+                total_chars += len(msg.content)
+            elif isinstance(msg.content, list):
+                for block in msg.content:
+                    if isinstance(block, dict):
+                        total_chars += len(str(block))
+
+            if msg.thinking:
+                total_chars += len(msg.thinking)
+
+            if msg.tool_calls:
+                total_chars += len(str(msg.tool_calls))
+
+        # Rough estimation: average 2.5 characters = 1 token
+        return int(total_chars / 2.5)
+
+    async def _summarize_messages(self):
+        """Message history summarization: summarize conversations between user messages when tokens exceed limit
+
+        Strategy (Agent mode):
+        - Keep all user messages (these are user intents)
+        - Summarize content between each user-user pair (agent execution process)
+        - If last round is still executing (has agent/tool messages but no next user), also summarize
+        - Structure: system -> user1 -> summary1 -> user2 -> summary2 -> user3 -> summary3 (if executing)
+
+        Summary is triggered when EITHER:
+        - Local token estimation exceeds limit
+        - API reported total_tokens exceeds limit
+        """
+        # Skip check if we just completed a summary (wait for next LLM call to update api_total_tokens)
+        if self._skip_next_token_check:
+            self._skip_next_token_check = False
+            return
+
+        estimated_tokens = self._estimate_tokens()
+
+        # Check both local estimation and API reported tokens
+        should_summarize = estimated_tokens > self.token_limit or self.api_total_tokens > self.token_limit
+
+        # If neither exceeded, no summary needed
+        if not should_summarize:
+            return
+
+        print(
+            f"\n{Colors.BRIGHT_YELLOW}📊 Token usage - Local estimate: {estimated_tokens}, API reported: {self.api_total_tokens}, Limit: {self.token_limit}{Colors.RESET}"
+        )
+        print(f"{Colors.BRIGHT_YELLOW}🔄 Triggering message history summarization...{Colors.RESET}")
+
+        # Find all user message indices (skip system prompt)
+        user_indices = [i for i, msg in enumerate(self.messages) if msg.role == "user" and i > 0]
+
+        # Need at least 1 user message to perform summary
+        if len(user_indices) < 1:
+            print(f"{Colors.BRIGHT_YELLOW}⚠️  Insufficient messages, cannot summarize{Colors.RESET}")
+            return
+
+        # Build new message list
+        new_messages = [self.messages[0]]  # Keep system prompt
+        summary_count = 0
+
+        # Iterate through each user message and summarize the execution process after it
+        for i, user_idx in enumerate(user_indices):
+            # Add current user message
+            new_messages.append(self.messages[user_idx])
+
+            # Determine message range to summarize
+            # If last user, go to end of message list; otherwise to before next user
+            if i < len(user_indices) - 1:
+                next_user_idx = user_indices[i + 1]
+            else:
+                next_user_idx = len(self.messages)
+
+            # Extract execution messages for this round
+            execution_messages = self.messages[user_idx + 1 : next_user_idx]
+
+            # If there are execution messages in this round, summarize them
+            if execution_messages:
+                summary_text = await self._create_summary(execution_messages, i + 1)
+                if summary_text:
+                    summary_message = Message(
+                        role="user",
+                        content=f"[Assistant Execution Summary]\n\n{summary_text}",
+                    )
+                    new_messages.append(summary_message)
+                    summary_count += 1
+
+        # Replace message list
+        self.messages = new_messages
+
+        # Skip next token check to avoid consecutive summary triggers
+        # (api_total_tokens will be updated after next LLM call)
+        self._skip_next_token_check = True
+
+        new_tokens = self._estimate_tokens()
+        print(f"{Colors.BRIGHT_GREEN}✓ Summary completed, local tokens: {estimated_tokens} → {new_tokens}{Colors.RESET}")
+        print(f"{Colors.DIM}  Structure: system + {len(user_indices)} user messages + {summary_count} summaries{Colors.RESET}")
+        print(f"{Colors.DIM}  Note: API token count will update on next LLM call{Colors.RESET}")
+
+    async def _create_summary(self, messages: list[Message], round_num: int) -> str:
+        """Create summary for one execution round
+
+        Args:
+            messages: List of messages to summarize
+            round_num: Round number
+
+        Returns:
+            Summary text
+        """
+        if not messages:
+            return ""
+
+        # Build summary content
+        summary_content = f"Round {round_num} execution process:\n\n"
+        for msg in messages:
+            if msg.role == "assistant":
+                content_text = msg.content if isinstance(msg.content, str) else str(msg.content)
+                summary_content += f"Assistant: {content_text}\n"
+                if msg.tool_calls:
+                    tool_names = [tc.function.name for tc in msg.tool_calls]
+                    summary_content += f"  → Called tools: {', '.join(tool_names)}\n"
+            elif msg.role == "tool":
+                result_preview = msg.content if isinstance(msg.content, str) else str(msg.content)
+                summary_content += f"  ← Tool returned: {result_preview}...\n"
+
+        # Call LLM to generate concise summary
+        try:
+            summary_prompt = f"""Please provide a concise summary of the following Agent execution process:
+
+{summary_content}
+
+Requirements:
+1. Focus on what tasks were completed and which tools were called
+2. Keep key execution results and important findings
+3. Be concise and clear, within 1000 words
+4. Use English
+5. Do not include "user" related content, only summarize the Agent's execution process"""
+
+            summary_msg = Message(role="user", content=summary_prompt)
+            response = await self.llm.generate(
+                messages=[
+                    Message(
+                        role="system",
+                        content="You are an assistant skilled at summarizing Agent execution processes.",
+                    ),
+                    summary_msg,
+                ]
+            )
+
+            summary_text = response.content
+            print(f"{Colors.BRIGHT_GREEN}✓ Summary for round {round_num} generated successfully{Colors.RESET}")
+            return summary_text
+
+        except Exception as e:
+            print(f"{Colors.BRIGHT_RED}✗ Summary generation failed for round {round_num}: {e}{Colors.RESET}")
+            # Use simple text summary on failure
+            return summary_content
+
+    async def run(self, cancel_event: Optional[asyncio.Event] = None) -> str:
+        """Execute agent loop until task is complete or max steps reached.
+
+        Args:
+            cancel_event: Optional asyncio.Event that can be set to cancel execution.
+                          When set, the agent will stop at the next safe checkpoint
+                          (after completing the current step to keep messages consistent).
+
+        Returns:
+            The final response content, or error message (including cancellation message).
+        """
+        # Set cancellation event (can also be set via self.cancel_event before calling run())
+        if cancel_event is not None:
+            self.cancel_event = cancel_event
+
+        # Start new run, initialize log file
+        self.logger.start_new_run()
+        print(f"{Colors.DIM}📝 Log file: {self.logger.get_log_file_path()}{Colors.RESET}")
+
+        step = 0
+        run_start_time = perf_counter()
+
+        while step < self.max_steps:
+            # Check for cancellation at start of each step
+            if self._check_cancelled():
+                self._cleanup_incomplete_messages()
+                cancel_msg = "Task cancelled by user."
+                print(f"\n{Colors.BRIGHT_YELLOW}⚠️  {cancel_msg}{Colors.RESET}")
+                return cancel_msg
+
+            step_start_time = perf_counter()
+            # Check and summarize message history to prevent context overflow
+            await self._summarize_messages()
+
+            # Step header with proper width calculation
+            BOX_WIDTH = 58
+            step_text = f"{Colors.BOLD}{Colors.BRIGHT_CYAN}💭 Step {step + 1}/{self.max_steps}{Colors.RESET}"
+            step_display_width = calculate_display_width(step_text)
+            padding = max(0, BOX_WIDTH - 1 - step_display_width)  # -1 for leading space
+
+            print(f"\n{Colors.DIM}╭{'─' * BOX_WIDTH}╮{Colors.RESET}")
+            print(f"{Colors.DIM}│{Colors.RESET} {step_text}{' ' * padding}{Colors.DIM}│{Colors.RESET}")
+            print(f"{Colors.DIM}╰{'─' * BOX_WIDTH}╯{Colors.RESET}")
+
+            # Get tool list for LLM call
+            tool_list = list(self.tools.values())
+
+            # Log LLM request and call LLM with Tool objects directly
+            self.logger.log_request(messages=self.messages, tools=tool_list)
+
+            try:
+                response = await self.llm.generate(messages=self.messages, tools=tool_list)
+            except Exception as e:
+                # Check if it's a retry exhausted error
+                from .retry import RetryExhaustedError
+
+                if isinstance(e, RetryExhaustedError):
+                    error_msg = f"LLM call failed after {e.attempts} retries\nLast error: {str(e.last_exception)}"
+                    print(f"\n{Colors.BRIGHT_RED}❌ Retry failed:{Colors.RESET} {error_msg}")
+                else:
+                    error_msg = f"LLM call failed: {str(e)}"
+                    print(f"\n{Colors.BRIGHT_RED}❌ Error:{Colors.RESET} {error_msg}")
+                return error_msg
+
+            # Accumulate API reported token usage
+            if response.usage:
+                self.api_total_tokens = response.usage.total_tokens
+
+            # Log LLM response
+            self.logger.log_response(
+                content=response.content,
+                thinking=response.thinking,
+                tool_calls=response.tool_calls,
+                finish_reason=response.finish_reason,
+            )
+
+            # Add assistant message
+            assistant_msg = Message(
+                role="assistant",
+                content=response.content,
+                thinking=response.thinking,
+                tool_calls=response.tool_calls,
+            )
+            self.messages.append(assistant_msg)
+
+            # Print thinking if present
+            if response.thinking:
+                print(f"\n{Colors.BOLD}{Colors.MAGENTA}🧠 Thinking:{Colors.RESET}")
+                print(f"{Colors.DIM}{response.thinking}{Colors.RESET}")
+
+            # Print assistant response
+            if response.content:
+                print(f"\n{Colors.BOLD}{Colors.BRIGHT_BLUE}🤖 Assistant:{Colors.RESET}")
+                print(f"{response.content}")
+
+            # Check if task is complete (no tool calls)
+            if not response.tool_calls:
+                step_elapsed = perf_counter() - step_start_time
+                total_elapsed = perf_counter() - run_start_time
+                print(f"\n{Colors.DIM}⏱️  Step {step + 1} completed in {step_elapsed:.2f}s (total: {total_elapsed:.2f}s){Colors.RESET}")
+                return response.content
+
+            # Check for cancellation before executing tools
+            if self._check_cancelled():
+                self._cleanup_incomplete_messages()
+                cancel_msg = "Task cancelled by user."
+                print(f"\n{Colors.BRIGHT_YELLOW}⚠️  {cancel_msg}{Colors.RESET}")
+                return cancel_msg
+
+            # Execute tool calls
+            for tool_call in response.tool_calls:
+                tool_call_id = tool_call.id
+                function_name = tool_call.function.name
+                arguments = tool_call.function.arguments
+
+                # Tool call header
+                print(f"\n{Colors.BRIGHT_YELLOW}🔧 Tool Call:{Colors.RESET} {Colors.BOLD}{Colors.CYAN}{function_name}{Colors.RESET}")
+
+                # Arguments (formatted display)
+                print(f"{Colors.DIM}   Arguments:{Colors.RESET}")
+                # Truncate each argument value to avoid overly long output
+                truncated_args = {}
+                for key, value in arguments.items():
+                    value_str = str(value)
+                    if len(value_str) > 200:
+                        truncated_args[key] = value_str[:200] + "..."
+                    else:
+                        truncated_args[key] = value
+                args_json = json.dumps(truncated_args, indent=2, ensure_ascii=False)
+                for line in args_json.split("\n"):
+                    print(f"   {Colors.DIM}{line}{Colors.RESET}")
+
+                # Execute tool
+                if function_name not in self.tools:
+                    result = ToolResult(
+                        success=False,
+                        content="",
+                        error=f"Unknown tool: {function_name}",
+                    )
+                else:
+                    try:
+                        tool = self.tools[function_name]
+                        result = await tool.execute(**arguments)
+                    except Exception as e:
+                        # Catch all exceptions during tool execution, convert to failed ToolResult
+                        import traceback
+
+                        error_detail = f"{type(e).__name__}: {str(e)}"
+                        error_trace = traceback.format_exc()
+                        result = ToolResult(
+                            success=False,
+                            content="",
+                            error=f"Tool execution failed: {error_detail}\n\nTraceback:\n{error_trace}",
+                        )
+
+                # Log tool execution result
+                self.logger.log_tool_result(
+                    tool_name=function_name,
+                    arguments=arguments,
+                    result_success=result.success,
+                    result_content=result.content if result.success else None,
+                    result_error=result.error if not result.success else None,
+                )
+
+                # Print result
+                if result.success:
+                    result_text = result.content
+                    if len(result_text) > 300:
+                        result_text = result_text[:300] + f"{Colors.DIM}...{Colors.RESET}"
+                    print(f"{Colors.BRIGHT_GREEN}✓ Result:{Colors.RESET} {result_text}")
+                else:
+                    print(f"{Colors.BRIGHT_RED}✗ Error:{Colors.RESET} {Colors.RED}{result.error}{Colors.RESET}")
+
+                # Add tool result message
+                tool_msg = Message(
+                    role="tool",
+                    content=result.content if result.success else f"Error: {result.error}",
+                    tool_call_id=tool_call_id,
+                    name=function_name,
+                )
+                self.messages.append(tool_msg)
+
+                # Check for cancellation after each tool execution
+                if self._check_cancelled():
+                    self._cleanup_incomplete_messages()
+                    cancel_msg = "Task cancelled by user."
+                    print(f"\n{Colors.BRIGHT_YELLOW}⚠️  {cancel_msg}{Colors.RESET}")
+                    return cancel_msg
+
+            step_elapsed = perf_counter() - step_start_time
+            total_elapsed = perf_counter() - run_start_time
+            print(f"\n{Colors.DIM}⏱️  Step {step + 1} completed in {step_elapsed:.2f}s (total: {total_elapsed:.2f}s){Colors.RESET}")
+
+            step += 1
+
+        # Max steps reached
+        error_msg = f"Task couldn't be completed after {self.max_steps} steps."
+        print(f"\n{Colors.BRIGHT_YELLOW}⚠️  {error_msg}{Colors.RESET}")
+        return error_msg
+
+    def get_history(self) -> list[Message]:
+        """Get message history."""
+        return self.messages.copy()

mini_agent/cli.py

@@ -0,0 +1,834 @@
+"""
+Mini Agent - Interactive Runtime Example
+
+Usage:
+    mini-agent [--workspace DIR]
+
+Examples:
+    mini-agent                              # Use current directory as workspace
+    mini-agent --workspace /path/to/dir     # Use specific workspace directory
+"""
+
+import argparse
+import asyncio
+import platform
+import subprocess
+import sys
+import threading
+from datetime import datetime
+from pathlib import Path
+from typing import List
+
+from prompt_toolkit import PromptSession
+from prompt_toolkit.auto_suggest import AutoSuggestFromHistory
+from prompt_toolkit.completion import WordCompleter
+from prompt_toolkit.history import FileHistory
+from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.styles import Style
+
+from mini_agent import LLMClient
+from mini_agent.agent import Agent
+from mini_agent.config import Config
+from mini_agent.schema import LLMProvider
+from mini_agent.tools.base import Tool
+from mini_agent.tools.bash_tool import BashKillTool, BashOutputTool, BashTool
+from mini_agent.tools.file_tools import EditTool, ReadTool, WriteTool
+from mini_agent.tools.mcp_loader import cleanup_mcp_connections, load_mcp_tools_async, set_mcp_timeout_config
+from mini_agent.tools.note_tool import SessionNoteTool
+from mini_agent.tools.skill_tool import create_skill_tools
+from mini_agent.utils import calculate_display_width
+
+
+# ANSI color codes
+class Colors:
+    """Terminal color definitions"""
+
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+
+    # Foreground colors
+    BLACK = "\033[30m"
+    RED = "\033[31m"
+    GREEN = "\033[32m"
+    YELLOW = "\033[33m"
+    BLUE = "\033[34m"
+    MAGENTA = "\033[35m"
+    CYAN = "\033[36m"
+    WHITE = "\033[37m"
+
+    # Bright colors
+    BRIGHT_BLACK = "\033[90m"
+    BRIGHT_RED = "\033[91m"
+    BRIGHT_GREEN = "\033[92m"
+    BRIGHT_YELLOW = "\033[93m"
+    BRIGHT_BLUE = "\033[94m"
+    BRIGHT_MAGENTA = "\033[95m"
+    BRIGHT_CYAN = "\033[96m"
+    BRIGHT_WHITE = "\033[97m"
+
+    # Background colors
+    BG_RED = "\033[41m"
+    BG_GREEN = "\033[42m"
+    BG_YELLOW = "\033[43m"
+    BG_BLUE = "\033[44m"
+
+
+def get_log_directory() -> Path:
+    """Get the log directory path."""
+    return Path.home() / ".mini-agent" / "log"
+
+
+def show_log_directory(open_file_manager: bool = True) -> None:
+    """Show log directory contents and optionally open file manager.
+
+    Args:
+        open_file_manager: Whether to open the system file manager
+    """
+    log_dir = get_log_directory()
+
+    print(f"\n{Colors.BRIGHT_CYAN}📁 Log Directory: {log_dir}{Colors.RESET}")
+
+    if not log_dir.exists() or not log_dir.is_dir():
+        print(f"{Colors.RED}Log directory does not exist: {log_dir}{Colors.RESET}\n")
+        return
+
+    log_files = list(log_dir.glob("*.log"))
+
+    if not log_files:
+        print(f"{Colors.YELLOW}No log files found in directory.{Colors.RESET}\n")
+        return
+
+    # Sort by modification time (newest first)
+    log_files.sort(key=lambda x: x.stat().st_mtime, reverse=True)
+
+    print(f"{Colors.DIM}{'─' * 60}{Colors.RESET}")
+    print(f"{Colors.BOLD}{Colors.BRIGHT_YELLOW}Available Log Files (newest first):{Colors.RESET}")
+
+    for i, log_file in enumerate(log_files[:10], 1):
+        mtime = datetime.fromtimestamp(log_file.stat().st_mtime)
+        size = log_file.stat().st_size
+        size_str = f"{size:,}" if size < 1024 else f"{size / 1024:.1f}K"
+        print(f"  {Colors.GREEN}{i:2d}.{Colors.RESET} {Colors.BRIGHT_WHITE}{log_file.name}{Colors.RESET}")
+        print(f"      {Colors.DIM}Modified: {mtime.strftime('%Y-%m-%d %H:%M:%S')}, Size: {size_str}{Colors.RESET}")
+
+    if len(log_files) > 10:
+        print(f"  {Colors.DIM}... and {len(log_files) - 10} more files{Colors.RESET}")
+
+    print(f"{Colors.DIM}{'─' * 60}{Colors.RESET}")
+
+    # Open file manager
+    if open_file_manager:
+        _open_directory_in_file_manager(log_dir)
+
+    print()
+
+
+def _open_directory_in_file_manager(directory: Path) -> None:
+    """Open directory in system file manager (cross-platform)."""
+    system = platform.system()
+
+    try:
+        if system == "Darwin":
+            subprocess.run(["open", str(directory)], check=False)
+        elif system == "Windows":
+            subprocess.run(["explorer", str(directory)], check=False)
+        elif system == "Linux":
+            subprocess.run(["xdg-open", str(directory)], check=False)
+    except FileNotFoundError:
+        print(f"{Colors.YELLOW}Could not open file manager. Please navigate manually.{Colors.RESET}")
+    except Exception as e:
+        print(f"{Colors.YELLOW}Error opening file manager: {e}{Colors.RESET}")
+
+
+def read_log_file(filename: str) -> None:
+    """Read and display a specific log file.
+
+    Args:
+        filename: The log filename to read
+    """
+    log_dir = get_log_directory()
+    log_file = log_dir / filename
+
+    if not log_file.exists() or not log_file.is_file():
+        print(f"\n{Colors.RED}❌ Log file not found: {log_file}{Colors.RESET}\n")
+        return
+
+    print(f"\n{Colors.BRIGHT_CYAN}📄 Reading: {log_file}{Colors.RESET}")
+    print(f"{Colors.DIM}{'─' * 80}{Colors.RESET}")
+
+    try:
+        with open(log_file, "r", encoding="utf-8") as f:
+            content = f.read()
+        print(content)
+        print(f"{Colors.DIM}{'─' * 80}{Colors.RESET}")
+        print(f"\n{Colors.GREEN}✅ End of file{Colors.RESET}\n")
+    except Exception as e:
+        print(f"\n{Colors.RED}❌ Error reading file: {e}{Colors.RESET}\n")
+
+
+def print_banner():
+    """Print welcome banner with proper alignment"""
+    BOX_WIDTH = 58
+    banner_text = f"{Colors.BOLD}🤖 Mini Agent - Multi-turn Interactive Session{Colors.RESET}"
+    banner_width = calculate_display_width(banner_text)
+
+    # Center the text with proper padding
+    total_padding = BOX_WIDTH - banner_width
+    left_padding = total_padding // 2
+    right_padding = total_padding - left_padding
+
+    print()
+    print(f"{Colors.BOLD}{Colors.BRIGHT_CYAN}╔{'═' * BOX_WIDTH}╗{Colors.RESET}")
+    print(
+        f"{Colors.BOLD}{Colors.BRIGHT_CYAN}║{Colors.RESET}{' ' * left_padding}{banner_text}{' ' * right_padding}{Colors.BOLD}{Colors.BRIGHT_CYAN}║{Colors.RESET}"
+    )
+    print(f"{Colors.BOLD}{Colors.BRIGHT_CYAN}╚{'═' * BOX_WIDTH}╝{Colors.RESET}")
+    print()
+
+
+def print_help():
+    """Print help information"""
+    help_text = f"""
+{Colors.BOLD}{Colors.BRIGHT_YELLOW}Available Commands:{Colors.RESET}
+  {Colors.BRIGHT_GREEN}/help{Colors.RESET}      - Show this help message
+  {Colors.BRIGHT_GREEN}/clear{Colors.RESET}     - Clear session history (keep system prompt)
+  {Colors.BRIGHT_GREEN}/history{Colors.RESET}   - Show current session message count
+  {Colors.BRIGHT_GREEN}/stats{Colors.RESET}     - Show session statistics
+  {Colors.BRIGHT_GREEN}/log{Colors.RESET}       - Show log directory and recent files
+  {Colors.BRIGHT_GREEN}/log <file>{Colors.RESET} - Read a specific log file
+  {Colors.BRIGHT_GREEN}/exit{Colors.RESET}      - Exit program (also: exit, quit, q)
+
+{Colors.BOLD}{Colors.BRIGHT_YELLOW}Keyboard Shortcuts:{Colors.RESET}
+  {Colors.BRIGHT_CYAN}Esc{Colors.RESET}        - Cancel current agent execution
+  {Colors.BRIGHT_CYAN}Ctrl+C{Colors.RESET}     - Exit program
+  {Colors.BRIGHT_CYAN}Ctrl+U{Colors.RESET}     - Clear current input line
+  {Colors.BRIGHT_CYAN}Ctrl+L{Colors.RESET}     - Clear screen
+  {Colors.BRIGHT_CYAN}Ctrl+J{Colors.RESET}     - Insert newline (also Ctrl+Enter)
+  {Colors.BRIGHT_CYAN}Tab{Colors.RESET}        - Auto-complete commands
+  {Colors.BRIGHT_CYAN}↑/↓{Colors.RESET}        - Browse command history
+  {Colors.BRIGHT_CYAN}→{Colors.RESET}          - Accept auto-suggestion
+
+{Colors.BOLD}{Colors.BRIGHT_YELLOW}Usage:{Colors.RESET}
+  - Enter your task directly, Agent will help you complete it
+  - Agent remembers all conversation content in this session
+  - Use {Colors.BRIGHT_GREEN}/clear{Colors.RESET} to start a new session
+  - Press {Colors.BRIGHT_CYAN}Enter{Colors.RESET} to submit your message
+  - Use {Colors.BRIGHT_CYAN}Ctrl+J{Colors.RESET} to insert line breaks within your message
+"""
+    print(help_text)
+
+
+def print_session_info(agent: Agent, workspace_dir: Path, model: str):
+    """Print session information with proper alignment"""
+    BOX_WIDTH = 58
+
+    def print_info_line(text: str):
+        """Print a single info line with proper padding"""
+        # Account for leading space
+        text_width = calculate_display_width(text)
+        padding = max(0, BOX_WIDTH - 1 - text_width)
+        print(f"{Colors.DIM}│{Colors.RESET} {text}{' ' * padding}{Colors.DIM}│{Colors.RESET}")
+
+    # Top border
+    print(f"{Colors.DIM}┌{'─' * BOX_WIDTH}┐{Colors.RESET}")
+
+    # Header (centered)
+    header_text = f"{Colors.BRIGHT_CYAN}Session Info{Colors.RESET}"
+    header_width = calculate_display_width(header_text)
+    header_padding_total = BOX_WIDTH - 1 - header_width  # -1 for leading space
+    header_padding_left = header_padding_total // 2
+    header_padding_right = header_padding_total - header_padding_left
+    print(f"{Colors.DIM}│{Colors.RESET} {' ' * header_padding_left}{header_text}{' ' * header_padding_right}{Colors.DIM}│{Colors.RESET}")
+
+    # Divider
+    print(f"{Colors.DIM}├{'─' * BOX_WIDTH}┤{Colors.RESET}")
+
+    # Info lines
+    print_info_line(f"Model: {model}")
+    print_info_line(f"Workspace: {workspace_dir}")
+    print_info_line(f"Message History: {len(agent.messages)} messages")
+    print_info_line(f"Available Tools: {len(agent.tools)} tools")
+
+    # Bottom border
+    print(f"{Colors.DIM}└{'─' * BOX_WIDTH}┘{Colors.RESET}")
+    print()
+    print(f"{Colors.DIM}Type {Colors.BRIGHT_GREEN}/help{Colors.DIM} for help, {Colors.BRIGHT_GREEN}/exit{Colors.DIM} to quit{Colors.RESET}")
+    print()
+
+
+def print_stats(agent: Agent, session_start: datetime):
+    """Print session statistics"""
+    duration = datetime.now() - session_start
+    hours, remainder = divmod(int(duration.total_seconds()), 3600)
+    minutes, seconds = divmod(remainder, 60)
+
+    # Count different types of messages
+    user_msgs = sum(1 for m in agent.messages if m.role == "user")
+    assistant_msgs = sum(1 for m in agent.messages if m.role == "assistant")
+    tool_msgs = sum(1 for m in agent.messages if m.role == "tool")
+
+    print(f"\n{Colors.BOLD}{Colors.BRIGHT_CYAN}Session Statistics:{Colors.RESET}")
+    print(f"{Colors.DIM}{'─' * 40}{Colors.RESET}")
+    print(f"  Session Duration: {hours:02d}:{minutes:02d}:{seconds:02d}")
+    print(f"  Total Messages: {len(agent.messages)}")
+    print(f"    - User Messages: {Colors.BRIGHT_GREEN}{user_msgs}{Colors.RESET}")
+    print(f"    - Assistant Replies: {Colors.BRIGHT_BLUE}{assistant_msgs}{Colors.RESET}")
+    print(f"    - Tool Calls: {Colors.BRIGHT_YELLOW}{tool_msgs}{Colors.RESET}")
+    print(f"  Available Tools: {len(agent.tools)}")
+    if agent.api_total_tokens > 0:
+        print(f"  API Tokens Used: {Colors.BRIGHT_MAGENTA}{agent.api_total_tokens:,}{Colors.RESET}")
+    print(f"{Colors.DIM}{'─' * 40}{Colors.RESET}\n")
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse command line arguments
+
+    Returns:
+        Parsed arguments
+    """
+    parser = argparse.ArgumentParser(
+        description="Mini Agent - AI assistant with file tools and MCP support",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  mini-agent                              # Use current directory as workspace
+  mini-agent --workspace /path/to/dir     # Use specific workspace directory
+  mini-agent log                          # Show log directory and recent files
+  mini-agent log agent_run_xxx.log        # Read a specific log file
+        """,
+    )
+    parser.add_argument(
+        "--workspace",
+        "-w",
+        type=str,
+        default=None,
+        help="Workspace directory (default: current directory)",
+    )
+    parser.add_argument(
+        "--version",
+        "-v",
+        action="version",
+        version="mini-agent 0.1.0",
+    )
+
+    # Subcommands
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # log subcommand
+    log_parser = subparsers.add_parser("log", help="Show log directory or read log files")
+    log_parser.add_argument(
+        "filename",
+        nargs="?",
+        default=None,
+        help="Log filename to read (optional, shows directory if omitted)",
+    )
+
+    return parser.parse_args()
+
+
+async def initialize_base_tools(config: Config):
+    """Initialize base tools (independent of workspace)
+
+    These tools are loaded from package configuration and don't depend on workspace.
+    Note: File tools are now workspace-dependent and initialized in add_workspace_tools()
+
+    Args:
+        config: Configuration object
+
+    Returns:
+        Tuple of (list of tools, skill loader if skills enabled)
+    """
+
+    tools = []
+    skill_loader = None
+
+    # 1. Bash tool and Bash Output tool
+    if config.tools.enable_bash:
+        bash_tool = BashTool()
+        tools.append(bash_tool)
+        print(f"{Colors.GREEN}✅ Loaded Bash tool{Colors.RESET}")
+
+        bash_output_tool = BashOutputTool()
+        tools.append(bash_output_tool)
+        print(f"{Colors.GREEN}✅ Loaded Bash Output tool{Colors.RESET}")
+
+        bash_kill_tool = BashKillTool()
+        tools.append(bash_kill_tool)
+        print(f"{Colors.GREEN}✅ Loaded Bash Kill tool{Colors.RESET}")
+
+    # 3. Claude Skills (loaded from package directory)
+    if config.tools.enable_skills:
+        print(f"{Colors.BRIGHT_CYAN}Loading Claude Skills...{Colors.RESET}")
+        try:
+            # Resolve skills directory with priority search
+            # Expand ~ to user home directory for portability
+            skills_path = Path(config.tools.skills_dir).expanduser()
+            if skills_path.is_absolute():
+                skills_dir = str(skills_path)
+            else:
+                # Search in priority order:
+                # 1. Current directory (dev mode: ./skills or ./mini_agent/skills)
+                # 2. Package directory (installed: site-packages/mini_agent/skills)
+                search_paths = [
+                    skills_path,  # ./skills for backward compatibility
+                    Path("mini_agent") / skills_path,  # ./mini_agent/skills
+                    Config.get_package_dir() / skills_path,  # site-packages/mini_agent/skills
+                ]
+
+                # Find first existing path
+                skills_dir = str(skills_path)  # default
+                for path in search_paths:
+                    if path.exists():
+                        skills_dir = str(path.resolve())
+                        break
+
+            skill_tools, skill_loader = create_skill_tools(skills_dir)
+            if skill_tools:
+                tools.extend(skill_tools)
+                print(f"{Colors.GREEN}✅ Loaded Skill tool (get_skill){Colors.RESET}")
+            else:
+                print(f"{Colors.YELLOW}⚠️  No available Skills found{Colors.RESET}")
+        except Exception as e:
+            print(f"{Colors.YELLOW}⚠️  Failed to load Skills: {e}{Colors.RESET}")
+
+    # 4. MCP tools (loaded with priority search)
+    if config.tools.enable_mcp:
+        print(f"{Colors.BRIGHT_CYAN}Loading MCP tools...{Colors.RESET}")
+        try:
+            # Apply MCP timeout configuration from config.yaml
+            mcp_config = config.tools.mcp
+            set_mcp_timeout_config(
+                connect_timeout=mcp_config.connect_timeout,
+                execute_timeout=mcp_config.execute_timeout,
+                sse_read_timeout=mcp_config.sse_read_timeout,
+            )
+            print(
+                f"{Colors.DIM}  MCP timeouts: connect={mcp_config.connect_timeout}s, "
+                f"execute={mcp_config.execute_timeout}s, sse_read={mcp_config.sse_read_timeout}s{Colors.RESET}"
+            )
+
+            # Use priority search for mcp.json
+            mcp_config_path = Config.find_config_file(config.tools.mcp_config_path)
+            if mcp_config_path:
+                mcp_tools = await load_mcp_tools_async(str(mcp_config_path))
+                if mcp_tools:
+                    tools.extend(mcp_tools)
+                    print(f"{Colors.GREEN}✅ Loaded {len(mcp_tools)} MCP tools (from: {mcp_config_path}){Colors.RESET}")
+                else:
+                    print(f"{Colors.YELLOW}⚠️  No available MCP tools found{Colors.RESET}")
+            else:
+                print(f"{Colors.YELLOW}⚠️  MCP config file not found: {config.tools.mcp_config_path}{Colors.RESET}")
+        except Exception as e:
+            print(f"{Colors.YELLOW}⚠️  Failed to load MCP tools: {e}{Colors.RESET}")
+
+    print()  # Empty line separator
+    return tools, skill_loader
+
+
+def add_workspace_tools(tools: List[Tool], config: Config, workspace_dir: Path):
+    """Add workspace-dependent tools
+
+    These tools need to know the workspace directory.
+
+    Args:
+        tools: Existing tools list to add to
+        config: Configuration object
+        workspace_dir: Workspace directory path
+    """
+    # Ensure workspace directory exists
+    workspace_dir.mkdir(parents=True, exist_ok=True)
+
+    # File tools - need workspace to resolve relative paths
+    if config.tools.enable_file_tools:
+        tools.extend(
+            [
+                ReadTool(workspace_dir=str(workspace_dir)),
+                WriteTool(workspace_dir=str(workspace_dir)),
+                EditTool(workspace_dir=str(workspace_dir)),
+            ]
+        )
+        print(f"{Colors.GREEN}✅ Loaded file operation tools (workspace: {workspace_dir}){Colors.RESET}")
+
+    # Session note tool - needs workspace to store memory file
+    if config.tools.enable_note:
+        tools.append(SessionNoteTool(memory_file=str(workspace_dir / ".agent_memory.json")))
+        print(f"{Colors.GREEN}✅ Loaded session note tool{Colors.RESET}")
+
+
+async def run_agent(workspace_dir: Path):
+    """Run interactive Agent
+
+    Args:
+        workspace_dir: Workspace directory path
+    """
+    session_start = datetime.now()
+
+    # 1. Load configuration from package directory
+    config_path = Config.get_default_config_path()
+
+    if not config_path.exists():
+        print(f"{Colors.RED}❌ Configuration file not found{Colors.RESET}")
+        print()
+        print(f"{Colors.BRIGHT_CYAN}📦 Configuration Search Path:{Colors.RESET}")
+        print(f"  {Colors.DIM}1) mini_agent/config/config.yaml{Colors.RESET} (development)")
+        print(f"  {Colors.DIM}2) ~/.mini-agent/config/config.yaml{Colors.RESET} (user)")
+        print(f"  {Colors.DIM}3) <package>/config/config.yaml{Colors.RESET} (installed)")
+        print()
+        print(f"{Colors.BRIGHT_YELLOW}🚀 Quick Setup (Recommended):{Colors.RESET}")
+        print(
+            f"  {Colors.BRIGHT_GREEN}curl -fsSL https://raw.githubusercontent.com/MiniMax-AI/Mini-Agent/main/scripts/setup-config.sh | bash{Colors.RESET}"
+        )
+        print()
+        print(f"{Colors.DIM}  This will automatically:{Colors.RESET}")
+        print(f"{Colors.DIM}    • Create ~/.mini-agent/config/{Colors.RESET}")
+        print(f"{Colors.DIM}    • Download configuration files{Colors.RESET}")
+        print(f"{Colors.DIM}    • Guide you to add your API Key{Colors.RESET}")
+        print()
+        print(f"{Colors.BRIGHT_YELLOW}📝 Manual Setup:{Colors.RESET}")
+        user_config_dir = Path.home() / ".mini-agent" / "config"
+        example_config = Config.get_package_dir() / "config" / "config-example.yaml"
+        print(f"  {Colors.DIM}mkdir -p {user_config_dir}{Colors.RESET}")
+        print(f"  {Colors.DIM}cp {example_config} {user_config_dir}/config.yaml{Colors.RESET}")
+        print(f"  {Colors.DIM}# Then edit {user_config_dir}/config.yaml to add your API Key{Colors.RESET}")
+        print()
+        return
+
+    try:
+        config = Config.from_yaml(config_path)
+    except FileNotFoundError:
+        print(f"{Colors.RED}❌ Error: Configuration file not found: {config_path}{Colors.RESET}")
+        return
+    except ValueError as e:
+        print(f"{Colors.RED}❌ Error: {e}{Colors.RESET}")
+        print(f"{Colors.YELLOW}Please check the configuration file format{Colors.RESET}")
+        return
+    except Exception as e:
+        print(f"{Colors.RED}❌ Error: Failed to load configuration file: {e}{Colors.RESET}")
+        return
+
+    # 2. Initialize LLM client
+    from mini_agent.retry import RetryConfig as RetryConfigBase
+
+    # Convert configuration format
+    retry_config = RetryConfigBase(
+        enabled=config.llm.retry.enabled,
+        max_retries=config.llm.retry.max_retries,
+        initial_delay=config.llm.retry.initial_delay,
+        max_delay=config.llm.retry.max_delay,
+        exponential_base=config.llm.retry.exponential_base,
+        retryable_exceptions=(Exception,),
+    )
+
+    # Create retry callback function to display retry information in terminal
+    def on_retry(exception: Exception, attempt: int):
+        """Retry callback function to display retry information"""
+        print(f"\n{Colors.BRIGHT_YELLOW}⚠️  LLM call failed (attempt {attempt}): {str(exception)}{Colors.RESET}")
+        next_delay = retry_config.calculate_delay(attempt - 1)
+        print(f"{Colors.DIM}   Retrying in {next_delay:.1f}s (attempt {attempt + 1})...{Colors.RESET}")
+
+    # Convert provider string to LLMProvider enum
+    provider = LLMProvider.ANTHROPIC if config.llm.provider.lower() == "anthropic" else LLMProvider.OPENAI
+
+    llm_client = LLMClient(
+        api_key=config.llm.api_key,
+        provider=provider,
+        api_base=config.llm.api_base,
+        model=config.llm.model,
+        retry_config=retry_config if config.llm.retry.enabled else None,
+    )
+
+    # Set retry callback
+    if config.llm.retry.enabled:
+        llm_client.retry_callback = on_retry
+        print(f"{Colors.GREEN}✅ LLM retry mechanism enabled (max {config.llm.retry.max_retries} retries){Colors.RESET}")
+
+    # 3. Initialize base tools (independent of workspace)
+    tools, skill_loader = await initialize_base_tools(config)
+
+    # 4. Add workspace-dependent tools
+    add_workspace_tools(tools, config, workspace_dir)
+
+    # 5. Load System Prompt (with priority search)
+    system_prompt_path = Config.find_config_file(config.agent.system_prompt_path)
+    if system_prompt_path and system_prompt_path.exists():
+        system_prompt = system_prompt_path.read_text(encoding="utf-8")
+        print(f"{Colors.GREEN}✅ Loaded system prompt (from: {system_prompt_path}){Colors.RESET}")
+    else:
+        system_prompt = "You are Mini-Agent, an intelligent assistant powered by MiniMax M2.1 that can help users complete various tasks."
+        print(f"{Colors.YELLOW}⚠️  System prompt not found, using default{Colors.RESET}")
+
+    # 6. Inject Skills Metadata into System Prompt (Progressive Disclosure - Level 1)
+    if skill_loader:
+        skills_metadata = skill_loader.get_skills_metadata_prompt()
+        if skills_metadata:
+            # Replace placeholder with actual metadata
+            system_prompt = system_prompt.replace("{SKILLS_METADATA}", skills_metadata)
+            print(f"{Colors.GREEN}✅ Injected {len(skill_loader.loaded_skills)} skills metadata into system prompt{Colors.RESET}")
+        else:
+            # Remove placeholder if no skills
+            system_prompt = system_prompt.replace("{SKILLS_METADATA}", "")
+    else:
+        # Remove placeholder if skills not enabled
+        system_prompt = system_prompt.replace("{SKILLS_METADATA}", "")
+
+    # 7. Create Agent
+    agent = Agent(
+        llm_client=llm_client,
+        system_prompt=system_prompt,
+        tools=tools,
+        max_steps=config.agent.max_steps,
+        workspace_dir=str(workspace_dir),
+    )
+
+    # 8. Display welcome information
+    print_banner()
+    print_session_info(agent, workspace_dir, config.llm.model)
+
+    # 9. Setup prompt_toolkit session
+    # Command completer
+    command_completer = WordCompleter(
+        ["/help", "/clear", "/history", "/stats", "/log", "/exit", "/quit", "/q"],
+        ignore_case=True,
+        sentence=True,
+    )
+
+    # Custom style for prompt
+    prompt_style = Style.from_dict(
+        {
+            "prompt": "#00ff00 bold",  # Green and bold
+            "separator": "#666666",  # Gray
+        }
+    )
+
+    # Custom key bindings
+    kb = KeyBindings()
+
+    @kb.add("c-u")  # Ctrl+U: Clear current line
+    def _(event):
+        """Clear the current input line"""
+        event.current_buffer.reset()
+
+    @kb.add("c-l")  # Ctrl+L: Clear screen (optional bonus)
+    def _(event):
+        """Clear the screen"""
+        event.app.renderer.clear()
+
+    @kb.add("c-j")  # Ctrl+J (对应 Ctrl+Enter)
+    def _(event):
+        """Insert a newline"""
+        event.current_buffer.insert_text("\n")
+
+    # Create prompt session with history and auto-suggest
+    # Use FileHistory for persistent history across sessions (stored in user's home directory)
+    history_file = Path.home() / ".mini-agent" / ".history"
+    history_file.parent.mkdir(parents=True, exist_ok=True)
+    session = PromptSession(
+        history=FileHistory(str(history_file)),
+        auto_suggest=AutoSuggestFromHistory(),
+        completer=command_completer,
+        style=prompt_style,
+        key_bindings=kb,
+    )
+
+    # 10. Interactive loop
+    while True:
+        try:
+            # Get user input using prompt_toolkit
+            user_input = await session.prompt_async(
+                [
+                    ("class:prompt", "You"),
+                    ("", " › "),
+                ],
+                multiline=False,
+                enable_history_search=True,
+            )
+            user_input = user_input.strip()
+
+            if not user_input:
+                continue
+
+            # Handle commands
+            if user_input.startswith("/"):
+                command = user_input.lower()
+
+                if command in ["/exit", "/quit", "/q"]:
+                    print(f"\n{Colors.BRIGHT_YELLOW}👋 Goodbye! Thanks for using Mini Agent{Colors.RESET}\n")
+                    print_stats(agent, session_start)
+                    break
+
+                elif command == "/help":
+                    print_help()
+                    continue
+
+                elif command == "/clear":
+                    # Clear message history but keep system prompt
+                    old_count = len(agent.messages)
+                    agent.messages = [agent.messages[0]]  # Keep only system message
+                    print(f"{Colors.GREEN}✅ Cleared {old_count - 1} messages, starting new session{Colors.RESET}\n")
+                    continue
+
+                elif command == "/history":
+                    print(f"\n{Colors.BRIGHT_CYAN}Current session message count: {len(agent.messages)}{Colors.RESET}\n")
+                    continue
+
+                elif command == "/stats":
+                    print_stats(agent, session_start)
+                    continue
+
+                elif command == "/log" or command.startswith("/log "):
+                    # Parse /log command
+                    parts = user_input.split(maxsplit=1)
+                    if len(parts) == 1:
+                        # /log - show log directory
+                        show_log_directory(open_file_manager=True)
+                    else:
+                        # /log <filename> - read specific log file
+                        filename = parts[1].strip("\"'")
+                        read_log_file(filename)
+                    continue
+
+                else:
+                    print(f"{Colors.RED}❌ Unknown command: {user_input}{Colors.RESET}")
+                    print(f"{Colors.DIM}Type /help to see available commands{Colors.RESET}\n")
+                    continue
+
+            # Normal conversation - exit check
+            if user_input.lower() in ["exit", "quit", "q"]:
+                print(f"\n{Colors.BRIGHT_YELLOW}👋 Goodbye! Thanks for using Mini Agent{Colors.RESET}\n")
+                print_stats(agent, session_start)
+                break
+
+            # Run Agent with Esc cancellation support
+            print(
+                f"\n{Colors.BRIGHT_BLUE}Agent{Colors.RESET} {Colors.DIM}›{Colors.RESET} {Colors.DIM}Thinking... (Esc to cancel){Colors.RESET}\n"
+            )
+            agent.add_user_message(user_input)
+
+            # Create cancellation event
+            cancel_event = asyncio.Event()
+            agent.cancel_event = cancel_event
+
+            # Esc key listener thread
+            esc_listener_stop = threading.Event()
+            esc_cancelled = [False]  # Mutable container for thread access
+
+            def esc_key_listener():
+                """Listen for Esc key in a separate thread."""
+                if platform.system() == "Windows":
+                    try:
+                        import msvcrt
+
+                        while not esc_listener_stop.is_set():
+                            if msvcrt.kbhit():
+                                char = msvcrt.getch()
+                                if char == b"\x1b":  # Esc
+                                    print(f"\n{Colors.BRIGHT_YELLOW}⏹️  Esc pressed, cancelling...{Colors.RESET}")
+                                    esc_cancelled[0] = True
+                                    cancel_event.set()
+                                    break
+                            esc_listener_stop.wait(0.05)
+                    except Exception:
+                        pass
+                    return
+
+                # Unix/macOS
+                try:
+                    import select
+                    import termios
+                    import tty
+
+                    fd = sys.stdin.fileno()
+                    old_settings = termios.tcgetattr(fd)
+
+                    try:
+                        tty.setcbreak(fd)
+                        while not esc_listener_stop.is_set():
+                            rlist, _, _ = select.select([sys.stdin], [], [], 0.05)
+                            if rlist:
+                                char = sys.stdin.read(1)
+                                if char == "\x1b":  # Esc
+                                    print(f"\n{Colors.BRIGHT_YELLOW}⏹️  Esc pressed, cancelling...{Colors.RESET}")
+                                    esc_cancelled[0] = True
+                                    cancel_event.set()
+                                    break
+                    finally:
+                        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+                except Exception:
+                    pass
+
+            # Start Esc listener thread
+            esc_thread = threading.Thread(target=esc_key_listener, daemon=True)
+            esc_thread.start()
+
+            # Run agent with periodic cancellation check
+            try:
+                agent_task = asyncio.create_task(agent.run())
+
+                # Poll for cancellation while agent runs
+                while not agent_task.done():
+                    if esc_cancelled[0]:
+                        cancel_event.set()
+                    await asyncio.sleep(0.1)
+
+                # Get result
+                _ = agent_task.result()
+
+            except asyncio.CancelledError:
+                print(f"\n{Colors.BRIGHT_YELLOW}⚠️  Agent execution cancelled{Colors.RESET}")
+            finally:
+                agent.cancel_event = None
+                esc_listener_stop.set()
+                esc_thread.join(timeout=0.2)
+
+            # Visual separation
+            print(f"\n{Colors.DIM}{'─' * 60}{Colors.RESET}\n")
+
+        except KeyboardInterrupt:
+            print(f"\n\n{Colors.BRIGHT_YELLOW}👋 Interrupt signal detected, exiting...{Colors.RESET}\n")
+            print_stats(agent, session_start)
+            break
+
+        except Exception as e:
+            print(f"\n{Colors.RED}❌ Error: {e}{Colors.RESET}")
+            print(f"{Colors.DIM}{'─' * 60}{Colors.RESET}\n")
+
+    # 11. Cleanup MCP connections
+    try:
+        print(f"{Colors.BRIGHT_CYAN}Cleaning up MCP connections...{Colors.RESET}")
+        await cleanup_mcp_connections()
+        print(f"{Colors.GREEN}✅ Cleanup complete{Colors.RESET}\n")
+    except Exception as e:
+        print(f"{Colors.YELLOW}Error during cleanup (can be ignored): {e}{Colors.RESET}\n")
+
+
+def main():
+    """Main entry point for CLI"""
+    # Parse command line arguments
+    args = parse_args()
+
+    # Handle log subcommand
+    if args.command == "log":
+        if args.filename:
+            read_log_file(args.filename)
+        else:
+            show_log_directory(open_file_manager=True)
+        return
+
+    # Determine workspace directory
+    # Expand ~ to user home directory for portability
+    if args.workspace:
+        workspace_dir = Path(args.workspace).expanduser().absolute()
+    else:
+        # Use current working directory
+        workspace_dir = Path.cwd()
+
+    # Ensure workspace directory exists
+    workspace_dir.mkdir(parents=True, exist_ok=True)
+
+    # Run the agent (config always loaded from package directory)
+    asyncio.run(run_agent(workspace_dir))
+
+
+if __name__ == "__main__":
+    main()

mini_agent/config.py

@@ -0,0 +1,220 @@
+"""Configuration management module
+
+Provides unified configuration loading and management functionality
+"""
+
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field
+
+
+class RetryConfig(BaseModel):
+    """Retry configuration"""
+
+    enabled: bool = True
+    max_retries: int = 3
+    initial_delay: float = 1.0
+    max_delay: float = 60.0
+    exponential_base: float = 2.0
+
+
+class LLMConfig(BaseModel):
+    """LLM configuration"""
+
+    api_key: str
+    api_base: str = "https://api.minimax.io"
+    model: str = "MiniMax-M2.1"
+    provider: str = "anthropic"  # "anthropic" or "openai"
+    retry: RetryConfig = Field(default_factory=RetryConfig)
+
+
+class AgentConfig(BaseModel):
+    """Agent configuration"""
+
+    max_steps: int = 50
+    workspace_dir: str = "./workspace"
+    system_prompt_path: str = "system_prompt.md"
+
+
+class MCPConfig(BaseModel):
+    """MCP (Model Context Protocol) timeout configuration"""
+
+    connect_timeout: float = 10.0  # Connection timeout (seconds)
+    execute_timeout: float = 60.0  # Tool execution timeout (seconds)
+    sse_read_timeout: float = 120.0  # SSE read timeout (seconds)
+
+
+class ToolsConfig(BaseModel):
+    """Tools configuration"""
+
+    # Basic tools (file operations, bash)
+    enable_file_tools: bool = True
+    enable_bash: bool = True
+    enable_note: bool = True
+
+    # Skills
+    enable_skills: bool = True
+    skills_dir: str = "./skills"
+
+    # MCP tools
+    enable_mcp: bool = True
+    mcp_config_path: str = "mcp.json"
+    mcp: MCPConfig = Field(default_factory=MCPConfig)
+
+
+class Config(BaseModel):
+    """Main configuration class"""
+
+    llm: LLMConfig
+    agent: AgentConfig
+    tools: ToolsConfig
+
+    @classmethod
+    def load(cls) -> "Config":
+        """Load configuration from the default search path."""
+        config_path = cls.get_default_config_path()
+        if not config_path.exists():
+            raise FileNotFoundError("Configuration file not found. Run scripts/setup-config.sh or place config.yaml in mini_agent/config/.")
+        return cls.from_yaml(config_path)
+
+    @classmethod
+    def from_yaml(cls, config_path: str | Path) -> "Config":
+        """Load configuration from YAML file
+
+        Args:
+            config_path: Configuration file path
+
+        Returns:
+            Config instance
+
+        Raises:
+            FileNotFoundError: Configuration file does not exist
+            ValueError: Invalid configuration format or missing required fields
+        """
+        config_path = Path(config_path)
+
+        if not config_path.exists():
+            raise FileNotFoundError(f"Configuration file does not exist: {config_path}")
+
+        with open(config_path, encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+
+        if not data:
+            raise ValueError("Configuration file is empty")
+
+        # Parse LLM configuration
+        if "api_key" not in data:
+            raise ValueError("Configuration file missing required field: api_key")
+
+        if not data["api_key"] or data["api_key"] == "YOUR_API_KEY_HERE":
+            raise ValueError("Please configure a valid API Key")
+
+        # Parse retry configuration
+        retry_data = data.get("retry", {})
+        retry_config = RetryConfig(
+            enabled=retry_data.get("enabled", True),
+            max_retries=retry_data.get("max_retries", 3),
+            initial_delay=retry_data.get("initial_delay", 1.0),
+            max_delay=retry_data.get("max_delay", 60.0),
+            exponential_base=retry_data.get("exponential_base", 2.0),
+        )
+
+        llm_config = LLMConfig(
+            api_key=data["api_key"],
+            api_base=data.get("api_base", "https://api.minimax.io"),
+            model=data.get("model", "MiniMax-M2.1"),
+            provider=data.get("provider", "anthropic"),
+            retry=retry_config,
+        )
+
+        # Parse Agent configuration
+        agent_config = AgentConfig(
+            max_steps=data.get("max_steps", 50),
+            workspace_dir=data.get("workspace_dir", "./workspace"),
+            system_prompt_path=data.get("system_prompt_path", "system_prompt.md"),
+        )
+
+        # Parse tools configuration
+        tools_data = data.get("tools", {})
+
+        # Parse MCP configuration
+        mcp_data = tools_data.get("mcp", {})
+        mcp_config = MCPConfig(
+            connect_timeout=mcp_data.get("connect_timeout", 10.0),
+            execute_timeout=mcp_data.get("execute_timeout", 60.0),
+            sse_read_timeout=mcp_data.get("sse_read_timeout", 120.0),
+        )
+
+        tools_config = ToolsConfig(
+            enable_file_tools=tools_data.get("enable_file_tools", True),
+            enable_bash=tools_data.get("enable_bash", True),
+            enable_note=tools_data.get("enable_note", True),
+            enable_skills=tools_data.get("enable_skills", True),
+            skills_dir=tools_data.get("skills_dir", "./skills"),
+            enable_mcp=tools_data.get("enable_mcp", True),
+            mcp_config_path=tools_data.get("mcp_config_path", "mcp.json"),
+            mcp=mcp_config,
+        )
+
+        return cls(
+            llm=llm_config,
+            agent=agent_config,
+            tools=tools_config,
+        )
+
+    @staticmethod
+    def get_package_dir() -> Path:
+        """Get the package installation directory
+
+        Returns:
+            Path to the mini_agent package directory
+        """
+        # Get the directory where this config.py file is located
+        return Path(__file__).parent
+
+    @classmethod
+    def find_config_file(cls, filename: str) -> Path | None:
+        """Find configuration file with priority order
+
+        Search for config file in the following order of priority:
+        1) mini_agent/config/{filename} in current directory (development mode)
+        2) ~/.mini-agent/config/{filename} in user home directory
+        3) {package}/mini_agent/config/{filename} in package installation directory
+
+        Args:
+            filename: Configuration file name (e.g., "config.yaml", "mcp.json", "system_prompt.md")
+
+        Returns:
+            Path to found config file, or None if not found
+        """
+        # Priority 1: Development mode - current directory's config/ subdirectory
+        dev_config = Path.cwd() / "mini_agent" / "config" / filename
+        if dev_config.exists():
+            return dev_config
+
+        # Priority 2: User config directory
+        user_config = Path.home() / ".mini-agent" / "config" / filename
+        if user_config.exists():
+            return user_config
+
+        # Priority 3: Package installation directory's config/ subdirectory
+        package_config = cls.get_package_dir() / "config" / filename
+        if package_config.exists():
+            return package_config
+
+        return None
+
+    @classmethod
+    def get_default_config_path(cls) -> Path:
+        """Get the default config file path with priority search
+
+        Returns:
+            Path to config.yaml (prioritizes: dev config/ > user config/ > package config/)
+        """
+        config_path = cls.find_config_file("config.yaml")
+        if config_path:
+            return config_path
+
+        # Fallback to package config directory for error message purposes
+        return cls.get_package_dir() / "config" / "config.yaml"

mini_agent/config/config-example.yaml

@@ -0,0 +1,60 @@
+# Mini Agent Configuration Example
+# 
+# Configuration File Locations (in priority order):
+# 1) mini_agent/config/config.yaml - Development mode (current directory)
+# 2) ~/.mini-agent/config/config.yaml - User config directory
+# 3) <package>/mini_agent/config/config.yaml - Package installation directory
+#
+# To use this config:
+# - Copy this file to one of the above locations as config.yaml
+# - Fill in your API key and customize settings as needed
+# - All config files (config.yaml, mcp.json, system_prompt.md) are in the same directory
+
+# ===== LLM Configuration =====
+# MiniMax API Configuration
+# MiniMax provides both global and China platforms:
+# - Global: https://platform.minimax.io -> api_base: https://api.minimax.io
+# - China: https://platform.minimaxi.com -> api_base: https://api.minimaxi.com
+# Please choose based on your network environment and get API key from corresponding platform
+api_key: "YOUR_API_KEY_HERE"  # Replace with your MiniMax API Key
+api_base: "https://api.minimax.io"   # Global users (default)
+# api_base: "https://api.minimaxi.com"  # China users
+model: "MiniMax-M2.1"
+# LLM provider: "anthropic" or "openai"
+# For MiniMax API, the suffix (/anthropic or /v1) is auto-appended based on provider.
+# For third-party APIs (e.g., https://api.siliconflow.cn/v1), api_base is used as-is.
+provider: "anthropic"  # Default: anthropic
+
+# ===== Retry Configuration =====
+retry:
+  enabled: true           # Enable retry mechanism
+  max_retries: 3          # Maximum number of retries
+  initial_delay: 1.0      # Initial delay time (seconds)
+  max_delay: 60.0         # Maximum delay time (seconds)
+  exponential_base: 2.0   # Exponential backoff base (delay = initial_delay * base^attempt)
+
+# ===== Agent Configuration =====
+max_steps: 100  # Maximum execution steps
+workspace_dir: "./workspace"  # Working directory
+system_prompt_path: "system_prompt.md"  # System prompt file (same config directory)
+
+# ===== Tools Configuration =====
+tools:
+  # Basic tool switches
+  enable_file_tools: true  # File read/write/edit tools (ReadTool, WriteTool, EditTool)
+  enable_bash: true        # Bash command execution tool
+  enable_note: true        # Session note tool (SessionNoteTool)
+  
+  # Claude Skills
+  enable_skills: true      # Enable Skills
+  skills_dir: "./skills"   # Skills directory path
+  
+  # MCP Tools
+  enable_mcp: true         # Enable MCP tools
+  mcp_config_path: "mcp.json"  # MCP configuration file (same config directory)
+                           # Note: API Keys for MCP tools are configured in mcp.json
+  # MCP timeout configuration (prevents hanging on network issues)
+  mcp:
+    connect_timeout: 10.0    # Connection timeout in seconds (default: 10)
+    execute_timeout: 60.0    # Tool execution timeout in seconds (default: 60)
+    sse_read_timeout: 120.0  # SSE read timeout in seconds (default: 120)

mini_agent/config/mcp-example.json

@@ -0,0 +1,29 @@
+{
+    "mcpServers": {
+        "minimax_search": {
+            "description": "MiniMax Search - Powerful web search and intelligent browsing ⭐",
+            "type": "stdio",
+            "command": "uvx",
+            "args": [
+                "--from",
+                "git+https://github.com/MiniMax-AI/minimax_search",
+                "minimax-search"
+            ],
+            "env": {
+                "JINA_API_KEY": "",
+                "SERPER_API_KEY": "",
+                "MINIMAX_API_KEY": ""
+            },
+            "disabled": true
+        },
+        "memory": {
+            "description": "Memory - Knowledge graph memory system (long-term memory based on graph database)",
+            "command": "npx",
+            "args": [
+                "-y",
+                "@modelcontextprotocol/server-memory"
+            ],
+            "disabled": true
+        }
+    }
+}

mini_agent/config/system_prompt.md

@@ -0,0 +1,75 @@
+You are Mini-Agent, a versatile AI assistant powered by MiniMax, capable of executing complex tasks through a rich toolset and specialized skills.
+
+## Core Capabilities
+
+### 1. **Basic Tools**
+- **File Operations**: Read, write, edit files with full path support
+- **Bash Execution**: Run commands, manage git, packages, and system operations
+- **MCP Tools**: Access additional tools from configured MCP servers
+
+### 2. **Specialized Skills**
+You have access to specialized skills that provide expert guidance and capabilities for specific tasks.
+
+Skills are loaded dynamically using **Progressive Disclosure**:
+- **Level 1 (Metadata)**: You see skill names and descriptions (below) at startup
+- **Level 2 (Full Content)**: Load a skill's complete guidance using `get_skill(skill_name)`
+- **Level 3+ (Resources)**: Skills may reference additional files and scripts as needed
+
+**How to Use Skills:**
+1. Check the metadata below to identify relevant skills for your task
+2. Call `get_skill(skill_name)` to load the full guidance
+3. Follow the skill's instructions and use appropriate tools (bash, file operations, etc.)
+
+**Important Notes:**
+- Skills provide expert patterns and procedural knowledge
+- **For Python skills** (pdf, pptx, docx, xlsx, canvas-design, algorithmic-art): Setup Python environment FIRST (see Python Environment Management below)
+- Skills may reference scripts and resources - use bash or read_file to access them
+
+---
+
+{SKILLS_METADATA}
+
+## Working Guidelines
+
+### Task Execution
+1. **Analyze** the request and identify if a skill can help
+2. **Break down** complex tasks into clear, executable steps
+3. **Use skills** when appropriate for specialized guidance
+4. **Execute** tools systematically and check results
+5. **Report** progress and any issues encountered
+
+### File Operations
+- Use absolute paths or workspace-relative paths
+- Verify file existence before reading/editing
+- Create parent directories before writing files
+- Handle errors gracefully with clear messages
+
+### Bash Commands
+- Explain destructive operations before execution
+- Check command outputs for errors
+- Use appropriate error handling
+- Prefer specialized tools over raw commands when available
+
+### Python Environment Management
+**CRITICAL - Use `uv` for all Python operations. Before executing Python code:**
+1. Check/create venv: `if [ ! -d .venv ]; then uv venv; fi`
+2. Install packages: `uv pip install <package>`
+3. Run scripts: `uv run python script.py`
+4. If uv missing: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+
+**Python-based skills:** pdf, pptx, docx, xlsx, canvas-design, algorithmic-art 
+
+### Communication
+- Be concise but thorough in responses
+- Explain your approach before tool execution
+- Report errors with context and solutions
+- Summarize accomplishments when complete
+
+### Best Practices
+- **Don't guess** - use tools to discover missing information
+- **Be proactive** - infer intent and take reasonable actions
+- **Stay focused** - stop when the task is fulfilled
+- **Use skills** - leverage specialized knowledge when relevant
+
+## Workspace Context
+You are working in a workspace directory. All operations are relative to this context unless absolute paths are specified.

mini_agent/llm/__init__.py

@@ -0,0 +1,9 @@
+"""LLM clients package supporting both Anthropic and OpenAI protocols."""
+
+from .anthropic_client import AnthropicClient
+from .base import LLMClientBase
+from .llm_wrapper import LLMClient
+from .openai_client import OpenAIClient
+
+__all__ = ["LLMClientBase", "AnthropicClient", "OpenAIClient", "LLMClient"]
+

mini_agent/llm/anthropic_client.py

@@ -0,0 +1,293 @@
+"""Anthropic LLM client implementation."""
+
+import logging
+from typing import Any
+
+import anthropic
+
+from ..retry import RetryConfig, async_retry
+from ..schema import FunctionCall, LLMResponse, Message, TokenUsage, ToolCall
+from .base import LLMClientBase
+
+logger = logging.getLogger(__name__)
+
+
+class AnthropicClient(LLMClientBase):
+    """LLM client using Anthropic's protocol.
+
+    This client uses the official Anthropic SDK and supports:
+    - Extended thinking content
+    - Tool calling
+    - Retry logic
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        api_base: str = "https://api.minimaxi.com/anthropic",
+        model: str = "MiniMax-M2.1",
+        retry_config: RetryConfig | None = None,
+    ):
+        """Initialize Anthropic client.
+
+        Args:
+            api_key: API key for authentication
+            api_base: Base URL for the API (default: MiniMax Anthropic endpoint)
+            model: Model name to use (default: MiniMax-M2.1)
+            retry_config: Optional retry configuration
+        """
+        super().__init__(api_key, api_base, model, retry_config)
+
+        # Initialize Anthropic async client
+        self.client = anthropic.AsyncAnthropic(
+            base_url=api_base,
+            api_key=api_key,
+            default_headers={"Authorization": f"Bearer {api_key}"},
+        )
+
+    async def _make_api_request(
+        self,
+        system_message: str | None,
+        api_messages: list[dict[str, Any]],
+        tools: list[Any] | None = None,
+    ) -> anthropic.types.Message:
+        """Execute API request (core method that can be retried).
+
+        Args:
+            system_message: Optional system message
+            api_messages: List of messages in Anthropic format
+            tools: Optional list of tools
+
+        Returns:
+            Anthropic Message response
+
+        Raises:
+            Exception: API call failed
+        """
+        params = {
+            "model": self.model,
+            "max_tokens": 16384,
+            "messages": api_messages,
+        }
+
+        if system_message:
+            params["system"] = system_message
+
+        if tools:
+            params["tools"] = self._convert_tools(tools)
+
+        # Use Anthropic SDK's async messages.create
+        response = await self.client.messages.create(**params)
+        return response
+
+    def _convert_tools(self, tools: list[Any]) -> list[dict[str, Any]]:
+        """Convert tools to Anthropic format.
+
+        Anthropic tool format:
+        {
+            "name": "tool_name",
+            "description": "Tool description",
+            "input_schema": {
+                "type": "object",
+                "properties": {...},
+                "required": [...]
+            }
+        }
+
+        Args:
+            tools: List of Tool objects or dicts
+
+        Returns:
+            List of tools in Anthropic dict format
+        """
+        result = []
+        for tool in tools:
+            if isinstance(tool, dict):
+                result.append(tool)
+            elif hasattr(tool, "to_schema"):
+                # Tool object with to_schema method
+                result.append(tool.to_schema())
+            else:
+                raise TypeError(f"Unsupported tool type: {type(tool)}")
+        return result
+
+    def _convert_messages(self, messages: list[Message]) -> tuple[str | None, list[dict[str, Any]]]:
+        """Convert internal messages to Anthropic format.
+
+        Args:
+            messages: List of internal Message objects
+
+        Returns:
+            Tuple of (system_message, api_messages)
+        """
+        system_message = None
+        api_messages = []
+
+        for msg in messages:
+            if msg.role == "system":
+                system_message = msg.content
+                continue
+
+            # For user and assistant messages
+            if msg.role in ["user", "assistant"]:
+                # Handle assistant messages with thinking or tool calls
+                if msg.role == "assistant" and (msg.thinking or msg.tool_calls):
+                    # Build content blocks for assistant with thinking and/or tool calls
+                    content_blocks = []
+
+                    # Add thinking block if present
+                    if msg.thinking:
+                        content_blocks.append({"type": "thinking", "thinking": msg.thinking})
+
+                    # Add text content if present
+                    if msg.content:
+                        content_blocks.append({"type": "text", "text": msg.content})
+
+                    # Add tool use blocks
+                    if msg.tool_calls:
+                        for tool_call in msg.tool_calls:
+                            content_blocks.append(
+                                {
+                                    "type": "tool_use",
+                                    "id": tool_call.id,
+                                    "name": tool_call.function.name,
+                                    "input": tool_call.function.arguments,
+                                }
+                            )
+
+                    api_messages.append({"role": "assistant", "content": content_blocks})
+                else:
+                    api_messages.append({"role": msg.role, "content": msg.content})
+
+            # For tool result messages
+            elif msg.role == "tool":
+                # Anthropic uses user role with tool_result content blocks
+                api_messages.append(
+                    {
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "tool_result",
+                                "tool_use_id": msg.tool_call_id,
+                                "content": msg.content,
+                            }
+                        ],
+                    }
+                )
+
+        return system_message, api_messages
+
+    def _prepare_request(
+        self,
+        messages: list[Message],
+        tools: list[Any] | None = None,
+    ) -> dict[str, Any]:
+        """Prepare the request for Anthropic API.
+
+        Args:
+            messages: List of conversation messages
+            tools: Optional list of available tools
+
+        Returns:
+            Dictionary containing request parameters
+        """
+        system_message, api_messages = self._convert_messages(messages)
+
+        return {
+            "system_message": system_message,
+            "api_messages": api_messages,
+            "tools": tools,
+        }
+
+    def _parse_response(self, response: anthropic.types.Message) -> LLMResponse:
+        """Parse Anthropic response into LLMResponse.
+
+        Args:
+            response: Anthropic Message response
+
+        Returns:
+            LLMResponse object
+        """
+        # Extract text content, thinking, and tool calls
+        text_content = ""
+        thinking_content = ""
+        tool_calls = []
+
+        for block in response.content:
+            if block.type == "text":
+                text_content += block.text
+            elif block.type == "thinking":
+                thinking_content += block.thinking
+            elif block.type == "tool_use":
+                # Parse Anthropic tool_use block
+                tool_calls.append(
+                    ToolCall(
+                        id=block.id,
+                        type="function",
+                        function=FunctionCall(
+                            name=block.name,
+                            arguments=block.input,
+                        ),
+                    )
+                )
+
+        # Extract token usage from response
+        # Anthropic usage includes: input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens
+        usage = None
+        if hasattr(response, "usage") and response.usage:
+            input_tokens = response.usage.input_tokens or 0
+            output_tokens = response.usage.output_tokens or 0
+            cache_read_tokens = getattr(response.usage, "cache_read_input_tokens", 0) or 0
+            cache_creation_tokens = getattr(response.usage, "cache_creation_input_tokens", 0) or 0
+            total_input_tokens = input_tokens + cache_read_tokens + cache_creation_tokens
+            usage = TokenUsage(
+                prompt_tokens=total_input_tokens,
+                completion_tokens=output_tokens,
+                total_tokens=total_input_tokens + output_tokens,
+            )
+
+        return LLMResponse(
+            content=text_content,
+            thinking=thinking_content if thinking_content else None,
+            tool_calls=tool_calls if tool_calls else None,
+            finish_reason=response.stop_reason or "stop",
+            usage=usage,
+        )
+
+    async def generate(
+        self,
+        messages: list[Message],
+        tools: list[Any] | None = None,
+    ) -> LLMResponse:
+        """Generate response from Anthropic LLM.
+
+        Args:
+            messages: List of conversation messages
+            tools: Optional list of available tools
+
+        Returns:
+            LLMResponse containing the generated content
+        """
+        # Prepare request
+        request_params = self._prepare_request(messages, tools)
+
+        # Make API request with retry logic
+        if self.retry_config.enabled:
+            # Apply retry logic
+            retry_decorator = async_retry(config=self.retry_config, on_retry=self.retry_callback)
+            api_call = retry_decorator(self._make_api_request)
+            response = await api_call(
+                request_params["system_message"],
+                request_params["api_messages"],
+                request_params["tools"],
+            )
+        else:
+            # Don't use retry
+            response = await self._make_api_request(
+                request_params["system_message"],
+                request_params["api_messages"],
+                request_params["tools"],
+            )
+
+        # Parse and return response
+        return self._parse_response(response)

mini_agent/llm/base.py

@@ -0,0 +1,84 @@
+"""Base class for LLM clients."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ..retry import RetryConfig
+from ..schema import LLMResponse, Message
+
+
+class LLMClientBase(ABC):
+    """Abstract base class for LLM clients.
+
+    This class defines the interface that all LLM clients must implement,
+    regardless of the underlying API protocol (Anthropic, OpenAI, etc.).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        api_base: str,
+        model: str,
+        retry_config: RetryConfig | None = None,
+    ):
+        """Initialize the LLM client.
+
+        Args:
+            api_key: API key for authentication
+            api_base: Base URL for the API
+            model: Model name to use
+            retry_config: Optional retry configuration
+        """
+        self.api_key = api_key
+        self.api_base = api_base
+        self.model = model
+        self.retry_config = retry_config or RetryConfig()
+
+        # Callback for tracking retry count
+        self.retry_callback = None
+
+    @abstractmethod
+    async def generate(
+        self,
+        messages: list[Message],
+        tools: list[Any] | None = None,
+    ) -> LLMResponse:
+        """Generate response from LLM.
+
+        Args:
+            messages: List of conversation messages
+            tools: Optional list of Tool objects or dicts
+
+        Returns:
+            LLMResponse containing the generated content, thinking, and tool calls
+        """
+        pass
+
+    @abstractmethod
+    def _prepare_request(
+        self,
+        messages: list[Message],
+        tools: list[Any] | None = None,
+    ) -> dict[str, Any]:
+        """Prepare the request payload for the API.
+
+        Args:
+            messages: List of conversation messages
+            tools: Optional list of available tools
+
+        Returns:
+            Dictionary containing the request payload
+        """
+        pass
+
+    @abstractmethod
+    def _convert_messages(self, messages: list[Message]) -> tuple[str | None, list[dict[str, Any]]]:
+        """Convert internal message format to API-specific format.
+
+        Args:
+            messages: List of internal Message objects
+
+        Returns:
+            Tuple of (system_message, api_messages)
+        """
+        pass

mini_agent/llm/llm_wrapper.py

@@ -0,0 +1,127 @@
+"""LLM client wrapper that supports multiple providers.
+
+This module provides a unified interface for different LLM providers
+(Anthropic and OpenAI) through a single LLMClient class.
+"""
+
+import logging
+
+from ..retry import RetryConfig
+from ..schema import LLMProvider, LLMResponse, Message
+from .anthropic_client import AnthropicClient
+from .base import LLMClientBase
+from .openai_client import OpenAIClient
+
+logger = logging.getLogger(__name__)
+
+
+class LLMClient:
+    """LLM Client wrapper supporting multiple providers.
+
+    This class provides a unified interface for different LLM providers.
+    It automatically instantiates the correct underlying client based on
+    the provider parameter.
+
+    For MiniMax API (api.minimax.io or api.minimaxi.com), it appends the
+    appropriate endpoint suffix based on provider:
+    - anthropic: /anthropic
+    - openai: /v1
+
+    For third-party APIs, it uses the api_base as-is.
+    """
+
+    # MiniMax API domains that need automatic suffix handling
+    MINIMAX_DOMAINS = ("api.minimax.io", "api.minimaxi.com")
+
+    def __init__(
+        self,
+        api_key: str,
+        provider: LLMProvider = LLMProvider.ANTHROPIC,
+        api_base: str = "https://api.minimaxi.com",
+        model: str = "MiniMax-M2.1",
+        retry_config: RetryConfig | None = None,
+    ):
+        """Initialize LLM client with specified provider.
+
+        Args:
+            api_key: API key for authentication
+            provider: LLM provider (anthropic or openai)
+            api_base: Base URL for the API (default: https://api.minimaxi.com)
+                     For MiniMax API, suffix is auto-appended based on provider.
+                     For third-party APIs (e.g., https://api.siliconflow.cn/v1), used as-is.
+            model: Model name to use
+            retry_config: Optional retry configuration
+        """
+        self.provider = provider
+        self.api_key = api_key
+        self.model = model
+        self.retry_config = retry_config or RetryConfig()
+
+        # Normalize api_base (remove trailing slash)
+        api_base = api_base.rstrip("/")
+
+        # Check if this is a MiniMax API endpoint
+        is_minimax = any(domain in api_base for domain in self.MINIMAX_DOMAINS)
+
+        if is_minimax:
+            # For MiniMax API, ensure correct suffix based on provider
+            # Strip any existing suffix first
+            api_base = api_base.replace("/anthropic", "").replace("/v1", "")
+            if provider == LLMProvider.ANTHROPIC:
+                full_api_base = f"{api_base}/anthropic"
+            elif provider == LLMProvider.OPENAI:
+                full_api_base = f"{api_base}/v1"
+            else:
+                raise ValueError(f"Unsupported provider: {provider}")
+        else:
+            # For third-party APIs, use api_base as-is
+            full_api_base = api_base
+
+        self.api_base = full_api_base
+
+        # Instantiate the appropriate client
+        self._client: LLMClientBase
+        if provider == LLMProvider.ANTHROPIC:
+            self._client = AnthropicClient(
+                api_key=api_key,
+                api_base=full_api_base,
+                model=model,
+                retry_config=retry_config,
+            )
+        elif provider == LLMProvider.OPENAI:
+            self._client = OpenAIClient(
+                api_key=api_key,
+                api_base=full_api_base,
+                model=model,
+                retry_config=retry_config,
+            )
+        else:
+            raise ValueError(f"Unsupported provider: {provider}")
+
+        logger.info("Initialized LLM client with provider: %s, api_base: %s", provider, full_api_base)
+
+    @property
+    def retry_callback(self):
+        """Get retry callback."""
+        return self._client.retry_callback
+
+    @retry_callback.setter
+    def retry_callback(self, value):
+        """Set retry callback."""
+        self._client.retry_callback = value
+
+    async def generate(
+        self,
+        messages: list[Message],
+        tools: list | None = None,
+    ) -> LLMResponse:
+        """Generate response from LLM.
+
+        Args:
+            messages: List of conversation messages
+            tools: Optional list of Tool objects or dicts
+
+        Returns:
+            LLMResponse containing the generated content
+        """
+        return await self._client.generate(messages, tools)

mini_agent/llm/openai_client.py

@@ -0,0 +1,295 @@
+"""OpenAI LLM client implementation."""
+
+import json
+import logging
+from typing import Any
+
+from openai import AsyncOpenAI
+
+from ..retry import RetryConfig, async_retry
+from ..schema import FunctionCall, LLMResponse, Message, TokenUsage, ToolCall
+from .base import LLMClientBase
+
+logger = logging.getLogger(__name__)
+
+
+class OpenAIClient(LLMClientBase):
+    """LLM client using OpenAI's protocol.
+
+    This client uses the official OpenAI SDK and supports:
+    - Reasoning content (via reasoning_split=True)
+    - Tool calling
+    - Retry logic
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        api_base: str = "https://api.minimaxi.com/v1",
+        model: str = "MiniMax-M2.1",
+        retry_config: RetryConfig | None = None,
+    ):
+        """Initialize OpenAI client.
+
+        Args:
+            api_key: API key for authentication
+            api_base: Base URL for the API (default: MiniMax OpenAI endpoint)
+            model: Model name to use (default: MiniMax-M2.1)
+            retry_config: Optional retry configuration
+        """
+        super().__init__(api_key, api_base, model, retry_config)
+
+        # Initialize OpenAI client
+        self.client = AsyncOpenAI(
+            api_key=api_key,
+            base_url=api_base,
+        )
+
+    async def _make_api_request(
+        self,
+        api_messages: list[dict[str, Any]],
+        tools: list[Any] | None = None,
+    ) -> Any:
+        """Execute API request (core method that can be retried).
+
+        Args:
+            api_messages: List of messages in OpenAI format
+            tools: Optional list of tools
+
+        Returns:
+            OpenAI ChatCompletion response (full response including usage)
+
+        Raises:
+            Exception: API call failed
+        """
+        params = {
+            "model": self.model,
+            "messages": api_messages,
+            # Enable reasoning_split to separate thinking content
+            "extra_body": {"reasoning_split": True},
+        }
+
+        if tools:
+            params["tools"] = self._convert_tools(tools)
+
+        # Use OpenAI SDK's chat.completions.create
+        response = await self.client.chat.completions.create(**params)
+        # Return full response to access usage info
+        return response
+
+    def _convert_tools(self, tools: list[Any]) -> list[dict[str, Any]]:
+        """Convert tools to OpenAI format.
+
+        Args:
+            tools: List of Tool objects or dicts
+
+        Returns:
+            List of tools in OpenAI dict format
+        """
+        result = []
+        for tool in tools:
+            if isinstance(tool, dict):
+                # If already a dict, check if it's in OpenAI format
+                if "type" in tool and tool["type"] == "function":
+                    result.append(tool)
+                else:
+                    # Assume it's in Anthropic format, convert to OpenAI
+                    result.append(
+                        {
+                            "type": "function",
+                            "function": {
+                                "name": tool["name"],
+                                "description": tool["description"],
+                                "parameters": tool["input_schema"],
+                            },
+                        }
+                    )
+            elif hasattr(tool, "to_openai_schema"):
+                # Tool object with to_openai_schema method
+                result.append(tool.to_openai_schema())
+            else:
+                raise TypeError(f"Unsupported tool type: {type(tool)}")
+        return result
+
+    def _convert_messages(self, messages: list[Message]) -> tuple[str | None, list[dict[str, Any]]]:
+        """Convert internal messages to OpenAI format.
+
+        Args:
+            messages: List of internal Message objects
+
+        Returns:
+            Tuple of (system_message, api_messages)
+            Note: OpenAI includes system message in the messages array
+        """
+        api_messages = []
+
+        for msg in messages:
+            if msg.role == "system":
+                # OpenAI includes system message in messages array
+                api_messages.append({"role": "system", "content": msg.content})
+                continue
+
+            # For user messages
+            if msg.role == "user":
+                api_messages.append({"role": "user", "content": msg.content})
+
+            # For assistant messages
+            elif msg.role == "assistant":
+                assistant_msg = {"role": "assistant"}
+
+                # Add content if present
+                if msg.content:
+                    assistant_msg["content"] = msg.content
+
+                # Add tool calls if present
+                if msg.tool_calls:
+                    tool_calls_list = []
+                    for tool_call in msg.tool_calls:
+                        tool_calls_list.append(
+                            {
+                                "id": tool_call.id,
+                                "type": "function",
+                                "function": {
+                                    "name": tool_call.function.name,
+                                    "arguments": json.dumps(tool_call.function.arguments),
+                                },
+                            }
+                        )
+                    assistant_msg["tool_calls"] = tool_calls_list
+
+                # IMPORTANT: Add reasoning_details if thinking is present
+                # This is CRITICAL for Interleaved Thinking to work properly!
+                # The complete response_message (including reasoning_details) must be
+                # preserved in Message History and passed back to the model in the next turn.
+                # This ensures the model's chain of thought is not interrupted.
+                if msg.thinking:
+                    assistant_msg["reasoning_details"] = [{"text": msg.thinking}]
+
+                api_messages.append(assistant_msg)
+
+            # For tool result messages
+            elif msg.role == "tool":
+                api_messages.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": msg.tool_call_id,
+                        "content": msg.content,
+                    }
+                )
+
+        return None, api_messages
+
+    def _prepare_request(
+        self,
+        messages: list[Message],
+        tools: list[Any] | None = None,
+    ) -> dict[str, Any]:
+        """Prepare the request for OpenAI API.
+
+        Args:
+            messages: List of conversation messages
+            tools: Optional list of available tools
+
+        Returns:
+            Dictionary containing request parameters
+        """
+        _, api_messages = self._convert_messages(messages)
+
+        return {
+            "api_messages": api_messages,
+            "tools": tools,
+        }
+
+    def _parse_response(self, response: Any) -> LLMResponse:
+        """Parse OpenAI response into LLMResponse.
+
+        Args:
+            response: OpenAI ChatCompletion response (full response object)
+
+        Returns:
+            LLMResponse object
+        """
+        # Get message from response
+        message = response.choices[0].message
+
+        # Extract text content
+        text_content = message.content or ""
+
+        # Extract thinking content from reasoning_details
+        thinking_content = ""
+        if hasattr(message, "reasoning_details") and message.reasoning_details:
+            # reasoning_details is a list of reasoning blocks
+            for detail in message.reasoning_details:
+                if hasattr(detail, "text"):
+                    thinking_content += detail.text
+
+        # Extract tool calls
+        tool_calls = []
+        if message.tool_calls:
+            for tool_call in message.tool_calls:
+                # Parse arguments from JSON string
+                arguments = json.loads(tool_call.function.arguments)
+
+                tool_calls.append(
+                    ToolCall(
+                        id=tool_call.id,
+                        type="function",
+                        function=FunctionCall(
+                            name=tool_call.function.name,
+                            arguments=arguments,
+                        ),
+                    )
+                )
+
+        # Extract token usage from response
+        usage = None
+        if hasattr(response, "usage") and response.usage:
+            usage = TokenUsage(
+                prompt_tokens=response.usage.prompt_tokens or 0,
+                completion_tokens=response.usage.completion_tokens or 0,
+                total_tokens=response.usage.total_tokens or 0,
+            )
+
+        return LLMResponse(
+            content=text_content,
+            thinking=thinking_content if thinking_content else None,
+            tool_calls=tool_calls if tool_calls else None,
+            finish_reason="stop",  # OpenAI doesn't provide finish_reason in the message
+            usage=usage,
+        )
+
+    async def generate(
+        self,
+        messages: list[Message],
+        tools: list[Any] | None = None,
+    ) -> LLMResponse:
+        """Generate response from OpenAI LLM.
+
+        Args:
+            messages: List of conversation messages
+            tools: Optional list of available tools
+
+        Returns:
+            LLMResponse containing the generated content
+        """
+        # Prepare request
+        request_params = self._prepare_request(messages, tools)
+
+        # Make API request with retry logic
+        if self.retry_config.enabled:
+            # Apply retry logic
+            retry_decorator = async_retry(config=self.retry_config, on_retry=self.retry_callback)
+            api_call = retry_decorator(self._make_api_request)
+            response = await api_call(
+                request_params["api_messages"],
+                request_params["tools"],
+            )
+        else:
+            # Don't use retry
+            response = await self._make_api_request(
+                request_params["api_messages"],
+                request_params["tools"],
+            )
+
+        # Parse and return response
+        return self._parse_response(response)

mini_agent/logger.py

@@ -0,0 +1,178 @@
+"""Agent run logger"""
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from .schema import Message, ToolCall
+
+
+class AgentLogger:
+    """Agent run logger
+
+    Responsible for recording the complete interaction process of each agent run, including:
+    - LLM requests and responses
+    - Tool calls and results
+    """
+
+    def __init__(self):
+        """Initialize logger
+
+        Logs are stored in ~/.mini-agent/log/ directory
+        """
+        # Use ~/.mini-agent/log/ directory for logs
+        self.log_dir = Path.home() / ".mini-agent" / "log"
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+        self.log_file = None
+        self.log_index = 0
+
+    def start_new_run(self):
+        """Start new run, create new log file"""
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        log_filename = f"agent_run_{timestamp}.log"
+        self.log_file = self.log_dir / log_filename
+        self.log_index = 0
+
+        # Write log header
+        with open(self.log_file, "w", encoding="utf-8") as f:
+            f.write("=" * 80 + "\n")
+            f.write(f"Agent Run Log - {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
+            f.write("=" * 80 + "\n\n")
+
+    def log_request(self, messages: list[Message], tools: list[Any] | None = None):
+        """Log LLM request
+
+        Args:
+            messages: Message list
+            tools: Tool list (optional)
+        """
+        self.log_index += 1
+
+        # Build complete request data structure
+        request_data = {
+            "messages": [],
+            "tools": [],
+        }
+
+        # Convert messages to JSON serializable format
+        for msg in messages:
+            msg_dict = {
+                "role": msg.role,
+                "content": msg.content,
+            }
+            if msg.thinking:
+                msg_dict["thinking"] = msg.thinking
+            if msg.tool_calls:
+                msg_dict["tool_calls"] = [tc.model_dump() for tc in msg.tool_calls]
+            if msg.tool_call_id:
+                msg_dict["tool_call_id"] = msg.tool_call_id
+            if msg.name:
+                msg_dict["name"] = msg.name
+
+            request_data["messages"].append(msg_dict)
+
+        # Only record tool names
+        if tools:
+            request_data["tools"] = [tool.name for tool in tools]
+
+        # Format as JSON
+        content = "LLM Request:\n\n"
+        content += json.dumps(request_data, indent=2, ensure_ascii=False)
+
+        self._write_log("REQUEST", content)
+
+    def log_response(
+        self,
+        content: str,
+        thinking: str | None = None,
+        tool_calls: list[ToolCall] | None = None,
+        finish_reason: str | None = None,
+    ):
+        """Log LLM response
+
+        Args:
+            content: Response content
+            thinking: Thinking content (optional)
+            tool_calls: Tool call list (optional)
+            finish_reason: Finish reason (optional)
+        """
+        self.log_index += 1
+
+        # Build complete response data structure
+        response_data = {
+            "content": content,
+        }
+
+        if thinking:
+            response_data["thinking"] = thinking
+
+        if tool_calls:
+            response_data["tool_calls"] = [tc.model_dump() for tc in tool_calls]
+
+        if finish_reason:
+            response_data["finish_reason"] = finish_reason
+
+        # Format as JSON
+        log_content = "LLM Response:\n\n"
+        log_content += json.dumps(response_data, indent=2, ensure_ascii=False)
+
+        self._write_log("RESPONSE", log_content)
+
+    def log_tool_result(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+        result_success: bool,
+        result_content: str | None = None,
+        result_error: str | None = None,
+    ):
+        """Log tool execution result
+
+        Args:
+            tool_name: Tool name
+            arguments: Tool arguments
+            result_success: Whether successful
+            result_content: Result content (on success)
+            result_error: Error message (on failure)
+        """
+        self.log_index += 1
+
+        # Build complete tool execution result data structure
+        tool_result_data = {
+            "tool_name": tool_name,
+            "arguments": arguments,
+            "success": result_success,
+        }
+
+        if result_success:
+            tool_result_data["result"] = result_content
+        else:
+            tool_result_data["error"] = result_error
+
+        # Format as JSON
+        content = "Tool Execution:\n\n"
+        content += json.dumps(tool_result_data, indent=2, ensure_ascii=False)
+
+        self._write_log("TOOL_RESULT", content)
+
+    def _write_log(self, log_type: str, content: str):
+        """Write log entry
+
+        Args:
+            log_type: Log type (REQUEST, RESPONSE, TOOL_RESULT)
+            content: Log content
+        """
+        if self.log_file is None:
+            return
+
+        with open(self.log_file, "a", encoding="utf-8") as f:
+            f.write("\n" + "-" * 80 + "\n")
+            f.write(f"[{self.log_index}] {log_type}\n")
+            f.write(f"Timestamp: {datetime.now().strftime('%Y-%m-%d %H:%M:%S.%f')[:-3]}\n")
+            f.write("-" * 80 + "\n")
+            f.write(content + "\n")
+
+    def get_log_file_path(self) -> Path:
+        """Get current log file path"""
+        return self.log_file

mini_agent/retry.py

@@ -0,0 +1,138 @@
+"""Elegant retry mechanism module
+
+Provides decorators and utility functions to support retry logic for async functions.
+
+Features:
+- Supports exponential backoff strategy
+- Configurable retry count and intervals
+- Supports specifying retryable exception types
+- Detailed logging
+- Fully decoupled, non-invasive to business code
+"""
+
+import asyncio
+import functools
+import logging
+from typing import Any, Callable, Type, TypeVar
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+class RetryConfig:
+    """Retry configuration class"""
+
+    def __init__(
+        self,
+        enabled: bool = True,
+        max_retries: int = 3,
+        initial_delay: float = 1.0,
+        max_delay: float = 60.0,
+        exponential_base: float = 2.0,
+        retryable_exceptions: tuple[Type[Exception], ...] = (Exception,),
+    ):
+        """
+        Args:
+            enabled: Whether to enable retry mechanism
+            max_retries: Maximum number of retries
+            initial_delay: Initial delay time (seconds)
+            max_delay: Maximum delay time (seconds)
+            exponential_base: Exponential backoff base
+            retryable_exceptions: Tuple of retryable exception types
+        """
+        self.enabled = enabled
+        self.max_retries = max_retries
+        self.initial_delay = initial_delay
+        self.max_delay = max_delay
+        self.exponential_base = exponential_base
+        self.retryable_exceptions = retryable_exceptions
+
+    def calculate_delay(self, attempt: int) -> float:
+        """Calculate delay time (exponential backoff)
+
+        Args:
+            attempt: Current attempt number (starting from 0)
+
+        Returns:
+            Delay time (seconds)
+        """
+        delay = self.initial_delay * (self.exponential_base**attempt)
+        return min(delay, self.max_delay)
+
+
+class RetryExhaustedError(Exception):
+    """Retry exhausted exception"""
+
+    def __init__(self, last_exception: Exception, attempts: int):
+        self.last_exception = last_exception
+        self.attempts = attempts
+        super().__init__(f"Retry failed after {attempts} attempts. Last error: {str(last_exception)}")
+
+
+def async_retry(
+    config: RetryConfig | None = None,
+    on_retry: Callable[[Exception, int], None] | None = None,
+) -> Callable:
+    """Async function retry decorator
+
+    Args:
+        config: Retry configuration object, uses default config if None
+        on_retry: Callback function on retry, receives exception and current attempt number
+
+    Returns:
+        Decorator function
+
+    Example:
+        ```python
+        @async_retry(RetryConfig(max_retries=3, initial_delay=1.0))
+        async def call_api():
+            # API call code
+            pass
+        ```
+    """
+    if config is None:
+        config = RetryConfig()
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        @functools.wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            last_exception: Exception | None = None
+
+            for attempt in range(config.max_retries + 1):
+                try:
+                    # Try to execute function
+                    return await func(*args, **kwargs)
+
+                except config.retryable_exceptions as e:
+                    last_exception = e
+
+                    # If this is the last attempt, don't retry
+                    if attempt >= config.max_retries:
+                        logger.error(f"Function {func.__name__} retry failed, reached maximum retry count {config.max_retries}")
+                        raise RetryExhaustedError(e, attempt + 1)
+
+                    # Calculate delay time
+                    delay = config.calculate_delay(attempt)
+
+                    # Log
+                    logger.warning(
+                        f"Function {func.__name__} call {attempt + 1} failed: {str(e)}, "
+                        f"retrying attempt {attempt + 2} after {delay:.2f} seconds"
+                    )
+
+                    # Call callback function
+                    if on_retry:
+                        on_retry(e, attempt + 1)
+
+                    # Wait before retry
+                    await asyncio.sleep(delay)
+
+            # Should not reach here in theory
+            if last_exception:
+                raise last_exception
+            raise Exception("Unknown error")
+
+        return wrapper
+
+    return decorator

mini_agent/schema/__init__.py

@@ -0,0 +1,19 @@
+"""Schema definitions for Mini-Agent."""
+
+from .schema import (
+    FunctionCall,
+    LLMProvider,
+    LLMResponse,
+    Message,
+    TokenUsage,
+    ToolCall,
+)
+
+__all__ = [
+    "FunctionCall",
+    "LLMProvider",
+    "LLMResponse",
+    "Message",
+    "TokenUsage",
+    "ToolCall",
+]

mini_agent/schema/schema.py

@@ -0,0 +1,55 @@
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class LLMProvider(str, Enum):
+    """LLM provider types."""
+
+    ANTHROPIC = "anthropic"
+    OPENAI = "openai"
+
+
+class FunctionCall(BaseModel):
+    """Function call details."""
+
+    name: str
+    arguments: dict[str, Any]  # Function arguments as dict
+
+
+class ToolCall(BaseModel):
+    """Tool call structure."""
+
+    id: str
+    type: str  # "function"
+    function: FunctionCall
+
+
+class Message(BaseModel):
+    """Chat message."""
+
+    role: str  # "system", "user", "assistant", "tool"
+    content: str | list[dict[str, Any]]  # Can be string or list of content blocks
+    thinking: str | None = None  # Extended thinking content for assistant messages
+    tool_calls: list[ToolCall] | None = None
+    tool_call_id: str | None = None
+    name: str | None = None  # For tool role
+
+
+class TokenUsage(BaseModel):
+    """Token usage statistics from LLM API response."""
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+
+
+class LLMResponse(BaseModel):
+    """LLM response."""
+
+    content: str
+    thinking: str | None = None  # Extended thinking blocks
+    tool_calls: list[ToolCall] | None = None
+    finish_reason: str
+    usage: TokenUsage | None = None  # Token usage from API response

mini_agent/skills/.claude-plugin/marketplace.json

@@ -0,0 +1,43 @@
+{
+  "name": "anthropic-agent-skills",
+  "owner": {
+    "name": "Keith Lazuka",
+    "email": "klazuka@anthropic.com"
+  },
+  "metadata": {
+    "description": "Anthropic example skills",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "document-skills",
+      "description": "Collection of document processing suite including Excel, Word, PowerPoint, and PDF capabilities",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./document-skills/xlsx",
+        "./document-skills/docx",
+        "./document-skills/pptx",
+        "./document-skills/pdf"
+      ]
+    },
+    {
+      "name": "example-skills",
+      "description": "Collection of example skills demonstrating various capabilities including skill creation, MCP building, visual design, algorithmic art, internal communications, web testing, artifact building, Slack GIFs, and theme styling",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./skill-creator",
+        "./mcp-builder",
+        "./canvas-design",
+        "./algorithmic-art",
+        "./internal-comms",
+        "./webapp-testing",
+        "./artifacts-builder",
+        "./slack-gif-creator",
+        "./theme-factory",
+        "./brand-guidelines"
+      ]
+    }
+  ]
+}

mini_agent/skills/.gitignore

@@ -0,0 +1,2 @@
+.DS_Store
+

mini_agent/skills/README.md

@@ -0,0 +1,123 @@
+# Skills
+Skills are folders of instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks. Skills teach Claude how to complete specific tasks in a repeatable way, whether that's creating documents with your company's brand guidelines, analyzing data using your organization's specific workflows, or automating personal tasks.
+
+For more information, check out:
+- [What are skills?](https://support.claude.com/en/articles/12512176-what-are-skills)
+- [Using skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
+- [How to create custom skills](https://support.claude.com/en/articles/12512198-creating-custom-skills)
+- [Equipping agents for the real world with Agent Skills](https://anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
+
+# About This Repository
+
+This repository contains example skills that demonstrate what's possible with Claude's skills system. These examples range from creative applications (art, music, design) to technical tasks (testing web apps, MCP server generation) to enterprise workflows (communications, branding, etc.).
+
+Each skill is self-contained in its own directory with a `SKILL.md` file containing the instructions and metadata that Claude uses. Browse through these examples to get inspiration for your own skills or to understand different patterns and approaches.
+
+The example skills in this repo are open source (Apache 2.0). We've also included the document creation & editing skills that power [Claude's document capabilities](https://www.anthropic.com/news/create-files) under the hood in the [`document-skills/`](./document-skills/) folder. These are source-available, not open source, but we wanted to share these with developers as a reference for more complex skills that are actively used in a production AI application.
+
+**Note:** These are reference examples for inspiration and learning. They showcase general-purpose capabilities rather than organization-specific workflows or sensitive content.
+
+## Disclaimer
+
+**These skills are provided for demonstration and educational purposes only.** While some of these capabilities may be available in Claude, the implementations and behaviors you receive from Claude may differ from what is shown in these examples. These examples are meant to illustrate patterns and possibilities. Always test skills thoroughly in your own environment before relying on them for critical tasks.
+
+# Example Skills
+
+This repository includes a diverse collection of example skills demonstrating different capabilities:
+
+## Creative & Design
+- **algorithmic-art** - Create generative art using p5.js with seeded randomness, flow fields, and particle systems
+- **canvas-design** - Design beautiful visual art in .png and .pdf formats using design philosophies
+- **slack-gif-creator** - Create animated GIFs optimized for Slack's size constraints
+
+## Development & Technical
+- **artifacts-builder** - Build complex claude.ai HTML artifacts using React, Tailwind CSS, and shadcn/ui components
+- **mcp-server** - Guide for creating high-quality MCP servers to integrate external APIs and services
+- **webapp-testing** - Test local web applications using Playwright for UI verification and debugging
+
+## Enterprise & Communication
+- **brand-guidelines** - Apply Anthropic's official brand colors and typography to artifacts
+- **internal-comms** - Write internal communications like status reports, newsletters, and FAQs
+- **theme-factory** - Style artifacts with 10 pre-set professional themes or generate custom themes on-the-fly
+
+## Meta Skills
+- **skill-creator** - Guide for creating effective skills that extend Claude's capabilities
+- **template-skill** - A basic template to use as a starting point for new skills
+
+# Document Skills
+
+The `document-skills/` subdirectory contains skills that Anthropic developed to help Claude create various document file formats. These skills demonstrate advanced patterns for working with complex file formats and binary data:
+
+- **docx** - Create, edit, and analyze Word documents with support for tracked changes, comments, formatting preservation, and text extraction
+- **pdf** - Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms
+- **pptx** - Create, edit, and analyze PowerPoint presentations with support for layouts, templates, charts, and automated slide generation
+- **xlsx** - Create, edit, and analyze Excel spreadsheets with support for formulas, formatting, data analysis, and visualization
+
+**Important Disclaimer:** These document skills are point-in-time snapshots and are not actively maintained or updated. Versions of these skills ship pre-included with Claude. They are primarily intended as reference examples to illustrate how Anthropic approaches developing more complex skills that work with binary file formats and document structures.
+
+# Try in Claude Code, Claude.ai, and the API
+
+## Claude Code
+You can register this repository as a Claude Code Plugin marketplace by running the following command in Claude Code:
+```
+/plugin marketplace add anthropics/skills
+```
+
+Then, to install a specific set of skills:
+1. Select `Browse and install plugins`
+2. Select `anthropic-agent-skills`
+3. Select `document-skills` or `example-skills`
+4. Select `Install now`
+
+Alternatively, directly install either Plugin via:
+```
+/plugin install document-skills@anthropic-agent-skills
+/plugin install example-skills@anthropic-agent-skills
+```
+
+After installing the plugin, you can use the skill by just mentioning it. For instance, if you install the `document-skills` plugin from the marketplace, you can ask Claude Code to do something like: "Use the PDF skill to extract the form fields from path/to/some-file.pdf"
+
+## Claude.ai
+
+These example skills are all already available to paid plans in Claude.ai. 
+
+To use any skill from this repository or upload custom skills, follow the instructions in [Using skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude#h_a4222fa77b).
+
+## Claude API
+
+You can use Anthropic's pre-built skills, and upload custom skills, via the Claude API. See the [Skills API Quickstart](https://docs.claude.com/en/api/skills-guide#creating-a-skill) for more.
+
+# Creating a Basic Skill
+
+Skills are simple to create - just a folder with a `SKILL.md` file containing YAML frontmatter and instructions. You can use the **template-skill** in this repository as a starting point:
+
+```markdown
+---
+name: my-skill-name
+description: A clear description of what this skill does and when to use it
+---
+
+# My Skill Name
+
+[Add your instructions here that Claude will follow when this skill is active]
+
+## Examples
+- Example usage 1
+- Example usage 2
+
+## Guidelines
+- Guideline 1
+- Guideline 2
+```
+
+The frontmatter requires only two fields:
+- `name` - A unique identifier for your skill (lowercase, hyphens for spaces)
+- `description` - A complete description of what the skill does and when to use it
+
+The markdown content below contains the instructions, examples, and guidelines that Claude will follow. For more details, see [How to create custom skills](https://support.claude.com/en/articles/12512198-creating-custom-skills).
+
+# Partner Skills
+
+Skills are a great way to teach Claude how to get better at using specific pieces of software. As we see awesome example skills from partners, we may highlight some of them here:
+
+- **Notion** - [Notion Skills for Claude](https://www.notion.so/notiondevs/Notion-Skills-for-Claude-28da4445d27180c7af1df7d8615723d0)

mini_agent/skills/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,405 @@
+# **Third-Party Notices**
+
+THE FOLLOWING SETS FORTH ATTRIBUTION NOTICES FOR THIRD PARTY SOFTWARE THAT MAY BE CONTAINED IN PORTIONS OF THIS PRODUCT.
+
+---
+
+## **BSD 2-Clause License**
+
+The following components are licensed under BSD 2-Clause License reproduced below:
+
+**imageio 2.37.0**, Copyright (c) 2014-2022, imageio developers
+
+**imageio-ffmpeg 0.6.0**, Copyright (c) 2019-2025, imageio 
+
+**License Text:**
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.  
+     
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+---
+
+## **GNU General Public License v3.0**
+
+The following components are licensed under GNU General Public License v3.0 reproduced below:
+
+**FFmpeg 7.0.2**, Copyright (c) 2000-2024 the FFmpeg developers
+
+Source Code: [https://ffmpeg.org/releases/ffmpeg-7.0.2.tar.xz](https://ffmpeg.org/releases/ffmpeg-7.0.2.tar.xz)
+
+**License Text:**
+
+GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007
+
+Copyright © 2007 Free Software Foundation, Inc. [https://fsf.org/](https://fsf.org/)
+
+Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
+
+Preamble
+
+The GNU General Public License is a free, copyleft license for software and other kinds of works.
+
+The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.
+
+When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.
+
+To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others.
+
+For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
+
+Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it.
+
+For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions.
+
+Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.
+
+Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.
+
+The precise terms and conditions for copying, distribution and modification follow.
+
+TERMS AND CONDITIONS
+
+0. Definitions.
+
+"This License" refers to version 3 of the GNU General Public License.
+
+"Copyright" also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.
+
+"The Program" refers to any copyrightable work licensed under this License. Each licensee is addressed as "you". "Licensees" and "recipients" may be individuals or organizations.
+
+To "modify" a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a "modified version" of the earlier work or a work "based on" the earlier work.
+
+A "covered work" means either the unmodified Program or a work based on the Program.
+
+To "propagate" a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.
+
+To "convey" a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.
+
+An interactive user interface displays "Appropriate Legal Notices" to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.
+
+1. Source Code.
+
+The "source code" for a work means the preferred form of the work for making modifications to it. "Object code" means any non-source form of a work.
+
+A "Standard Interface" means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.
+
+The "System Libraries" of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A "Major Component", in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.
+
+The "Corresponding Source" for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.
+
+The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.
+
+The Corresponding Source for a work in source code form is that same work.
+
+2. Basic Permissions.
+
+All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.
+
+You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.
+
+Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.
+
+3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.
+
+When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures.
+
+4. Conveying Verbatim Copies.
+
+You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.
+
+You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.
+
+5. Conveying Modified Source Versions.
+
+You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:
+
+a) The work must carry prominent notices stating that you modified it, and giving a relevant date.
+
+b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7\. This requirement modifies the requirement in section 4 to "keep intact all notices".
+
+c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it.
+
+d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so.
+
+A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an "aggregate" if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.
+
+6. Conveying Non-Source Forms.
+
+You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:
+
+a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange.
+
+b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge.
+
+c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b.
+
+d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements.
+
+e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d.
+
+A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.
+
+A "User Product" is either (1) a "consumer product", which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, "normally used" refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.
+
+"Installation Information" for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.
+
+If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).
+
+The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.
+
+Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.
+
+7. Additional Terms.
+
+"Additional permissions" are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.
+
+When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.
+
+Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:
+
+a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or
+
+b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or
+
+c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or
+
+d) Limiting the use for publicity purposes of names of licensors or authors of the material; or
+
+e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or
+
+f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors.
+
+All other non-permissive additional terms are considered "further restrictions" within the meaning of section 10\. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.
+
+If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.
+
+Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.
+
+8. Termination.
+
+You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).
+
+However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
+
+Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10\.
+
+9. Acceptance Not Required for Having Copies.
+
+You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.
+
+10. Automatic Licensing of Downstream Recipients.
+
+Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.
+
+An "entity transaction" is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.
+
+You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.
+
+11. Patents.
+
+A "contributor" is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's "contributor version".
+
+A contributor's "essential patent claims" are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, "control" includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.
+
+Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.
+
+In the following three paragraphs, a "patent license" is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To "grant" such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.
+
+If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. "Knowingly relying" means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.
+
+If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.
+
+A patent license is "discriminatory" if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007\.
+
+Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.
+
+12. No Surrender of Others' Freedom.
+
+If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.
+
+13. Use with the GNU Affero General Public License.
+
+Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.
+
+14. Revised Versions of this License.
+
+The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.
+
+If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program.
+
+Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.
+
+15. Disclaimer of Warranty.
+
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+16. Limitation of Liability.
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+17. Interpretation of Sections 15 and 16\.
+
+If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.
+
+END OF TERMS AND CONDITIONS
+
+How to Apply These Terms to Your New Programs
+
+If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
+
+To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.
+
+\<one line to give the program's name and a brief idea of what it does.\>   
+Copyright (C) \<year\>  \<name of author\>
+
+This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with this program. If not, see [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode:
+
+\<program\> Copyright (C) \<year\> \<name of author\>  
+This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'. This is free software, and you are welcome to redistribute it under certain conditions; type 'show c' for details.
+
+The hypothetical commands 'show w' and 'show c' should show the appropriate parts of the General Public License. Of course, your program's commands might be different; for a GUI interface, you would use an "about box".
+
+You should also get your employer (if you work as a programmer) or school, if any, to sign a "copyright disclaimer" for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
+
+The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read [https://www.gnu.org/licenses/why-not-lgpl.html](https://www.gnu.org/licenses/why-not-lgpl.html).
+
+---
+
+## **MIT-CMU License (HPND)**
+
+The following components are licensed under MIT-CMU License (HPND) reproduced below:
+
+**Pillow 11.3.0**, Copyright © 1997-2011 by Secret Labs AB, Copyright © 1995-2011 by Fredrik Lundh and contributors, Copyright © 2010 by Jeffrey A. Clark and contributors
+
+**License Text:**
+
+By obtaining, using, and/or copying this software and/or its associated documentation, you agree that you have read, understood, and will comply with the following terms and conditions:
+
+Permission to use, copy, modify and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies, and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Secret Labs AB or the author not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.
+
+SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+## **SIL Open Font License v1.1**
+
+The following fonts are licensed under SIL Open Font License v1.1 reproduced below:
+
+**Arsenal SC**, Copyright 2012 The Arsenal Project Authors ([andrij.design@gmail.com](mailto:andrij.design@gmail.com))
+
+**Big Shoulders**, Copyright 2019 The Big Shoulders Project Authors ([https://github.com/xotypeco/big\_shoulders](https://github.com/xotypeco/big_shoulders))
+
+**Boldonse**, Copyright 2024 The Boldonse Project Authors ([https://github.com/googlefonts/boldonse](https://github.com/googlefonts/boldonse))
+
+**Bricolage Grotesque**, Copyright 2022 The Bricolage Grotesque Project Authors ([https://github.com/ateliertriay/bricolage](https://github.com/ateliertriay/bricolage))
+
+**Crimson Pro**, Copyright 2018 The Crimson Pro Project Authors ([https://github.com/Fonthausen/CrimsonPro](https://github.com/Fonthausen/CrimsonPro))
+
+**DM Mono**, Copyright 2020 The DM Mono Project Authors ([https://www.github.com/googlefonts/dm-mono](https://www.github.com/googlefonts/dm-mono))
+
+**Erica One**, Copyright (c) 2011 by LatinoType Limitada ([luciano@latinotype.com](mailto:luciano@latinotype.com)), with Reserved Font Name "Erica One"
+
+**Geist Mono**, Copyright 2024 The Geist Project Authors ([https://github.com/vercel/geist-font.git](https://github.com/vercel/geist-font.git))
+
+**Gloock**, Copyright 2022 The Gloock Project Authors ([https://github.com/duartp/gloock](https://github.com/duartp/gloock))
+
+**IBM Plex Mono**, Copyright © 2017 IBM Corp., with Reserved Font Name "Plex"
+
+**Instrument Sans**, Copyright 2022 The Instrument Sans Project Authors ([https://github.com/Instrument/instrument-sans](https://github.com/Instrument/instrument-sans))
+
+**Italiana**, Copyright (c) 2011, Santiago Orozco ([hi@typemade.mx](mailto:hi@typemade.mx)), with Reserved Font Name "Italiana"
+
+**JetBrains Mono**, Copyright 2020 The JetBrains Mono Project Authors ([https://github.com/JetBrains/JetBrainsMono](https://github.com/JetBrains/JetBrainsMono))
+
+**Jura**, Copyright 2019 The Jura Project Authors ([https://github.com/ossobuffo/jura](https://github.com/ossobuffo/jura))
+
+**Libre Baskerville**, Copyright 2012 The Libre Baskerville Project Authors ([https://github.com/impallari/Libre-Baskerville](https://github.com/impallari/Libre-Baskerville)), with Reserved Font Name "Libre Baskerville"
+
+**Lora**, Copyright 2011 The Lora Project Authors ([https://github.com/cyrealtype/Lora-Cyrillic](https://github.com/cyrealtype/Lora-Cyrillic)), with Reserved Font Name "Lora"
+
+**National Park**, Copyright 2025 The National Park Project Authors ([https://github.com/benhoepner/National-Park](https://github.com/benhoepner/National-Park))
+
+**Nothing You Could Do**, Copyright (c) 2010, Kimberly Geswein (kimberlygeswein.com)
+
+**Outfit**, Copyright 2021 The Outfit Project Authors ([https://github.com/Outfitio/Outfit-Fonts](https://github.com/Outfitio/Outfit-Fonts))
+
+**Pixelify Sans**, Copyright 2021 The Pixelify Sans Project Authors ([https://github.com/eifetx/Pixelify-Sans](https://github.com/eifetx/Pixelify-Sans))
+
+**Poiret One**, Copyright (c) 2011, Denis Masharov ([denis.masharov@gmail.com](mailto:denis.masharov@gmail.com))
+
+**Red Hat Mono**, Copyright 2024 The Red Hat Project Authors ([https://github.com/RedHatOfficial/RedHatFont](https://github.com/RedHatOfficial/RedHatFont))
+
+**Silkscreen**, Copyright 2001 The Silkscreen Project Authors ([https://github.com/googlefonts/silkscreen](https://github.com/googlefonts/silkscreen))
+
+**Smooch Sans**, Copyright 2016 The Smooch Sans Project Authors ([https://github.com/googlefonts/smooch-sans](https://github.com/googlefonts/smooch-sans))
+
+**Tektur**, Copyright 2023 The Tektur Project Authors ([https://www.github.com/hyvyys/Tektur](https://www.github.com/hyvyys/Tektur))
+
+**Work Sans**, Copyright 2019 The Work Sans Project Authors ([https://github.com/weiweihuanghuang/Work-Sans](https://github.com/weiweihuanghuang/Work-Sans))
+
+**Young Serif**, Copyright 2023 The Young Serif Project Authors ([https://github.com/noirblancrouge/YoungSerif](https://github.com/noirblancrouge/YoungSerif))
+
+**License Text:**
+
+---
+
+## **SIL OPEN FONT LICENSE Version 1.1 \- 26 February 2007**
+
+PREAMBLE
+
+The goals of the Open Font License (OFL) are to stimulate worldwide development of collaborative font projects, to support the font creation efforts of academic and linguistic communities, and to provide a free and open framework in which fonts may be shared and improved in partnership with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and redistributed freely as long as they are not sold by themselves. The fonts, including any derivative works, can be bundled, embedded, redistributed and/or sold with any software provided that any reserved names are not used by derivative works. The fonts and derivatives, however, cannot be released under any other type of license. The requirement for fonts to remain under this license does not apply to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+
+"Font Software" refers to the set of files released by the Copyright Holder(s) under this license and clearly marked as such. This may include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting, or substituting \-- in part or in whole \-- any of the components of the Original Version, by changing formats or by porting the Font Software to a new environment.
+
+"Author" refers to any designer, engineer, programmer, technical writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of the Font Software, to use, study, copy, merge, embed, modify, redistribute, and sell modified and unmodified copies of the Font Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components, in Original or Modified Versions, may be sold by itself.  
+     
+2) Original or Modified Versions of the Font Software may be bundled, redistributed and/or sold with any software, provided that each copy contains the above copyright notice and this license. These can be included either as stand-alone text files, human-readable headers or in the appropriate machine-readable metadata fields within text or binary files as long as those fields can be easily viewed by the user.  
+     
+3) No Modified Version of the Font Software may use the Reserved Font Name(s) unless explicit written permission is granted by the corresponding Copyright Holder. This restriction only applies to the primary font name as presented to the users.  
+     
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font Software shall not be used to promote, endorse or advertise any Modified Version, except to acknowledge the contribution(s) of the Copyright Holder(s) and the Author(s) or with their explicit written permission.  
+     
+5) The Font Software, modified or unmodified, in part or in whole, must be distributed entirely under this license, and must not be distributed under any other license. The requirement for fonts to remain under this license does not apply to any document created using the Font Software.
+
+TERMINATION
+
+This license becomes null and void if any of the above conditions are not met.
+
+DISCLAIMER
+
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.  

mini_agent/skills/agent_skills_spec.md

@@ -0,0 +1,55 @@
+# Agent Skills Spec
+
+A skill is a folder of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks. In order for the folder to be recognized as a skill, it must contain a `SKILL.md` file. 
+
+# Skill Folder Layout
+
+A minimal skill folder looks like this: 
+
+```
+my-skill/
+  - SKILL.md
+```
+
+More complex skills can add additional directories and files as needed.
+
+
+# The SKILL.md file
+
+The skill's "entrypoint" is the `SKILL.md` file. It is the only file required to exist. The file must start with a YAML frontmatter followed by regular Markdown. 
+
+## YAML Frontmatter
+
+The YAML frontmatter has 2 required properties:
+
+- `name`
+    - The name of the skill in hyphen-case
+    - Restricted to lowercase Unicode alphanumeric + hyphen
+    - Must match the name of the directory containing the SKILL.md
+- `description` 
+    - Description of what the skill does and when Claude should use it
+
+There are 3 optional properties:
+
+- `license`
+    - The license applied to the skill
+    - We recommend keeping it short (either the name of a license or the name of a bundled license file)
+- `allowed-tools` 
+    - A list of tools that are pre-approved to run
+    - Currently only supported in Claude Code
+- `metadata`
+    - A map from string keys to string values
+    - Clients can use this to store additional properties not defined by the Agent Skills Spec
+    - We recommend making your key names reasonably unique to avoid accidental conflicts
+
+## Markdown Body
+
+The Markdown body has no restrictions on it.
+
+# Additional Information
+
+For a minimal example, see the `template-skill` example.
+
+# Version History
+
+- 1.0 (2025-10-16) Public Launch

mini_agent/skills/algorithmic-art/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.