openpaw-ai 0.4.0__tar.gz

openpaw_ai-0.4.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.0] - 2026-05-29
+
+### Added
+
+- **Structural refactor** — Layered architecture with clear stability contract: `model` (pure data) → `core` (config, prompts, utilities) → `agent` (runner, tools, middleware) → `workspace` (loader, runner, lifecycle) → `runtime` (orchestrator, queue, scheduling, subagents) → `channels` (external adapters).
+- **Multi-channel support** — Run multiple channels (Telegram, Discord) simultaneously in a single workspace. Each channel is isolated with its own session keys, activation filters, and trigger keywords.
+- **Workspace isolation** — Every workspace gets its own channels, queue, agent runner, and cron scheduler. No state leakage between workspaces.
+- **Cron & heartbeat scheduling** — APScheduler-based cron jobs from YAML definitions; proactive heartbeat check-ins with active-hours support, HEARTBEAT_OK suppression, and task summary injection.
+- **Sub-agent spawning** — Background concurrent workers via `spawn_agent` with isolated contexts, tool filtering, and session-scoped lifecycle tracking. Supports spawn profiles (`agent/team/*.yaml`) for specialized personas.
+- **Browser automation** — Playwright-based web browsing with accessibility tree navigation, domain allowlists/blocklists, cookie persistence, and screenshot/download support.
+- **Email integration** — Gmail send/receive via service account + domain-wide delegation. Supports search, reply, attachments, and recipient policy enforcement.
+- **GPT-Researcher builtin** — Deep research via WebSocket with streaming progress and report generation.
+- **Dynamic & persistent scheduling** — Agents can schedule one-time (`schedule_at`) or recurring (`schedule_every`) tasks at runtime, or create persistent YAML cron jobs via `cron_manager`.
+- **Queue-aware middleware** — Steer and interrupt modes let agents respond to new user messages mid-execution without losing context.
+- **Approval gates** — Human-in-the-loop authorization for dangerous tools with configurable timeout and default action.
+- **Token usage tracking** — Per-invocation metrics logged to JSONL for cost monitoring and `/status` queries.
+- **Runtime model switching** — Live provider/model switching via `/model` command without restart.
+- **Auto-compact** — Automatic conversation compaction when context window utilization exceeds a threshold.
+- **Session TTL** — Lazy conversation auto-reset after inactivity in group channels.
+- **Checkpoint pruning** — Automatic cleanup of orphaned conversation checkpoints on startup.
+- **Provider catalog** — Define provider connection details once in global config and reference by name from workspaces.
+- **Skills system** — Reusable knowledge patterns via `SKILL.md` files with progressive disclosure (summary vs full injection).
+- **Framework skills** — Bundled reference skills for team management, web browsing, and channel awareness.
+- **Status reminder middleware** — Automatic nudges for agents to update users after long silent tool chains.
+- **Session logging** — JSONL session logs for heartbeat, cron, and sub-agent runs readable by the main agent.
+- **Channel history & logs** — On-demand context fetch and persistent JSONL channel logging for group awareness.
+- **File persistence & enrichment** — Universal upload handling with Whisper transcription and Docling document conversion.
+- **Trusted Publishing support** — CI/CD workflows configured for PEP 740 Trusted Publishing to PyPI.
+- **Pre-commit hooks** — Ruff, mypy, and version sync checks.
+
+### Changed
+
+- CLI now supports single workspace, multiple workspaces, or wildcard `--all`.
+- Configuration deep-merges workspace `agent.yaml` over global `config.yaml`.
+- Error sanitization prevents internal details from leaking to channel users.
+
+### Fixed
+
+- Various race conditions in approval gate resolution and sub-agent cancellation.
+- Path traversal protection hardened across filesystem tools and inbound processors.
+
+[0.4.0]: https://github.com/johnsosoka/openpaw/releases/tag/v0.4.0

openpaw_ai-0.4.0/LICENSE

@@ -0,0 +1,75 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+Copyright (c) 2025-2026 John Sosoka
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
+
+> Required Notice: Copyright John Sosoka (https://johnsosoka.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

openpaw_ai-0.4.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: openpaw-ai
+Version: 0.4.0
+Summary: OpenPaw - Multi-Channel AI Agent Framework with LangGraph
+License: PolyForm Noncommercial 1.0.0
+License-File: LICENSE
+Keywords: ai,agent,langgraph,telegram,discord,bot
+Author: John Sosoka
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Communications :: Chat
+Classifier: Framework :: AsyncIO
+Provides-Extra: all-builtins
+Provides-Extra: email
+Provides-Extra: memory
+Provides-Extra: researcher
+Provides-Extra: voice
+Provides-Extra: web
+Requires-Dist: apscheduler (>=3.10.0,<4.0.0)
+Requires-Dist: discord.py (>=2.6.0,<3.0.0)
+Requires-Dist: docling (>=2.72.0,<3.0.0)
+Requires-Dist: easyocr (>=1.7.2,<2.0.0)
+Requires-Dist: elevenlabs (>=1.0.0) ; extra == "all-builtins"
+Requires-Dist: elevenlabs (>=1.0.0) ; extra == "voice"
+Requires-Dist: google-api-python-client (>=2.0.0) ; extra == "all-builtins"
+Requires-Dist: google-api-python-client (>=2.0.0) ; extra == "email"
+Requires-Dist: google-auth (>=2.0.0) ; extra == "all-builtins"
+Requires-Dist: google-auth (>=2.0.0) ; extra == "email"
+Requires-Dist: httpx (>=0.27.0) ; extra == "all-builtins"
+Requires-Dist: httpx (>=0.27.0) ; extra == "researcher"
+Requires-Dist: langchain (>=1.2.8,<2.0.0)
+Requires-Dist: langchain-anthropic (>=1.3.1,<2.0.0)
+Requires-Dist: langchain-aws (>=1.0.0,<2.0.0)
+Requires-Dist: langchain-community (>=0.4.0) ; extra == "all-builtins"
+Requires-Dist: langchain-community (>=0.4.0) ; extra == "web"
+Requires-Dist: langchain-fireworks (>=1.0.0,<2.0.0)
+Requires-Dist: langchain-openai (>=1.1.7,<2.0.0)
+Requires-Dist: langchain-xai (>=1.2.2,<2.0.0)
+Requires-Dist: langgraph (>=1.0.7,<2.0.0)
+Requires-Dist: langgraph-checkpoint-sqlite (>=2.0.0,<4.0.0)
+Requires-Dist: openai (>=1.0.0) ; extra == "all-builtins"
+Requires-Dist: openai (>=1.0.0) ; extra == "voice"
+Requires-Dist: opencv-python-headless (>=4.13.0.92,<5.0.0.0)
+Requires-Dist: playwright (>=1.58.0,<2.0.0)
+Requires-Dist: pydantic (>=2.12.5,<3.0.0)
+Requires-Dist: python-dotenv (>=1.2.1,<2.0.0)
+Requires-Dist: python-telegram-bot[job-queue] (>=22.6,<23.0)
+Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
+Requires-Dist: sqlite-vec (>=0.1.6) ; extra == "all-builtins"
+Requires-Dist: sqlite-vec (>=0.1.6) ; extra == "memory"
+Requires-Dist: websockets (>=12.0) ; extra == "all-builtins"
+Requires-Dist: websockets (>=12.0) ; extra == "researcher"
+Project-URL: Documentation, https://johnsosoka.github.io/OpenPaw/
+Project-URL: Homepage, https://johnsosoka.github.io/OpenPaw/
+Project-URL: Issues, https://github.com/johnsosoka/OpenPaw/issues
+Project-URL: Repository, https://github.com/johnsosoka/OpenPaw
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="docs/assets/images/logo.png" alt="OpenPaw" width="400">
+  <p><strong>A Friendly <a href="https://langchain-ai.github.io/langgraph/">LangChain/LangGraph</a> Multi-Agent Runner</strong></p>
+  <p>
+    <a href="https://github.com/johnsosoka/OpenPaw/actions/workflows/ci.yml"><img src="https://github.com/johnsosoka/OpenPaw/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+    <a href="https://github.com/johnsosoka/OpenPaw/actions/workflows/docs.yml"><img src="https://github.com/johnsosoka/OpenPaw/actions/workflows/docs.yml/badge.svg?branch=main" alt="Docs"></a>
+    <img src="https://github.com/johnsosoka/OpenPaw/actions/workflows/ai-code-review.yml/badge.svg" alt="AI Code Review">
+    <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+">
+    <img src="https://img.shields.io/badge/license-PolyForm%20Noncommercial-green" alt="License">
+  </p>
+</div>
+
+---
+
+> **Pre-1.0 Release (0.4.0)** — OpenPaw is actively developed. The API may evolve as we work towards a stable 1.0.0 release. Contributions and feedback are welcome.
+
+OpenPaw gives each agent its own workspace -- personality files, custom tools, scheduled tasks -- then gets out of the way. It handles the orchestration so you can focus on what your agents actually do.
+
+Agents can ingest documents, browse the web, search the internet, and manage their own files -- making them well-suited for research, information processing, and long-running autonomous workflows. Give them a schedule and they'll check in on their own.
+
+> **[Read the full documentation](https://johnsosoka.github.io/OpenPaw/)**
+
+## Highlights
+
+**First Class Document processing** -- Docling OCR/ICR turns scanned PDFs, DOCX, and PPTX into markdown automatically. Whisper transcribes voice messages on arrival.
+
+**Drop-in custom tools** -- Write a `@tool` function, put it in `agent/tools/`, restart. Your agent picks it up with zero wiring.
+
+**Multi-agent spawning** -- Agents spin up background workers for parallel tasks with full lifecycle tracking and result collection.
+
+**Dynamic tool assignment** -- Spawned sub-agents can be given a tailored tool loadout via allow/deny lists, so each worker gets only the capabilities it needs.
+
+**Cron scheduling and heartbeats** -- Recurring jobs, one-shot timers, proactive check-ins. Agents can even self-schedule follow-ups at runtime.
+
+**Browser automation** -- Playwright-driven web interaction via accessibility tree. Agents reference page elements by number, not CSS selectors.
+
+**Email integration** -- Send and receive email via Gmail with safe-by-default recipient policies. Read inbox, search, reply with threading, and manage attachments.
+
+**Deep research** -- Integrate with a self-hosted GPT-Researcher instance for multi-source research reports with citations. Agents submit queries via WebSocket and receive comprehensive markdown reports.
+
+**Approval gates** -- Human-in-the-loop authorization for dangerous operations, with configurable timeouts and channel-native UI.
+
+**Multi-channel support** -- Connect agents to Telegram, Discord, or both simultaneously. Trigger-based activation lets agents respond to @mentions, keyword triggers, or both in group chats. On-demand context fetch gives agents awareness of recent channel history when triggered.
+
+**Session management** -- Conversations auto-reset after inactivity (default 3 hours). Auto-compact rotates context when the window fills. Persistent channel logs give agents searchable message history.
+
+**Workspace isolation** -- Each agent gets its own SOUL.md personality, tools directory, conversation history, channels, and sandboxed filesystem.
+
+**Multi-provider LLM support** -- Anthropic, OpenAI, AWS Bedrock, xAI, and any OpenAI-compatible endpoint. Switch models at runtime with `/model`.
+
+**Memory and observability** -- Vector search for semantic recall, conversation archiving to markdown and JSON, and session logs for every cron, heartbeat, and sub-agent run. Full visibility into what your agents are doing and thinking.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+pip install openpaw-ai
+```
+
+For development from source:
+
+```bash
+git clone https://github.com/johnsosoka/OpenPaw.git
+cd OpenPaw
+poetry install
+```
+
+### 2. Scaffold a workspace
+
+```bash
+poetry run openpaw init my_agent \
+  --model anthropic:claude-sonnet-4-20250514 \
+  --channel telegram
+```
+
+### 3. Configure
+
+```bash
+cp config.example.yaml config.yaml
+```
+
+Add your API keys to `agent_workspaces/my_agent/config/.env`:
+
+```bash
+ANTHROPIC_API_KEY=your-key-here
+TELEGRAM_BOT_TOKEN=your-token-here
+```
+
+### 4. Run
+
+```bash
+poetry run openpaw -c config.yaml -w my_agent
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `openpaw init <name>` | Scaffold a new agent workspace |
+| `openpaw init <name> --model <provider:model>` | Scaffold with a pre-configured model |
+| `openpaw init <name> --channel telegram` | Scaffold with channel pre-configured (`telegram` or `discord`) |
+| `openpaw list` | List available workspaces |
+| `openpaw -c config.yaml -w <name>` | Run a single workspace |
+| `openpaw -c config.yaml -w name1,name2` | Run multiple workspaces |
+| `openpaw -c config.yaml --all` | Run all discovered workspaces |
+| `openpaw -c config.yaml -w <name> -v` | Run with verbose logging |
+
+All commands should be prefixed with `poetry run` when running from the project directory.
+
+## Agent Workspace Structure
+
+Each workspace lives under `agent_workspaces/<name>/` and is organized into five directories:
+
+```
+agent_workspaces/my_agent/
+├── agent/              # Identity and extensions
+│   ├── AGENT.md        # Capabilities and behavior guidelines
+│   ├── USER.md         # User context and preferences
+│   ├── SOUL.md         # Core personality and values
+│   ├── HEARTBEAT.md    # Session state scratchpad (agent-writable)
+│   ├── skills/         # Skill directories (SKILL.md format)
+│   ├── team/           # Spawn profiles (sub-agent personas)
+│   └── tools/          # Custom LangChain @tool functions
+├── config/             # Configuration (write-protected)
+│   ├── agent.yaml      # Per-workspace settings (model, channel, queue)
+│   ├── .env            # API keys and secrets
+│   └── crons/          # Scheduled task definitions
+├── .openpaw/           # Framework internals (write-protected)
+│   ├── conversations.db  # AsyncSqliteSaver checkpoint database
+│   ├── sessions.json     # Session/conversation thread state
+│   ├── token_usage.jsonl # Token usage metrics (append-only)
+│   └── subagents.yaml    # Sub-agent requests and results
+├── memory/             # Archived conversations and session logs
+│   ├── conversations/  # Conversation exports (markdown + JSON)
+│   └── logs/           # Session logs and channel history
+│       ├── channel/    # Persistent channel message logs (JSONL)
+│       └── sessions/   # Heartbeat, cron, and sub-agent session logs
+└── workspace/          # Agent work area (default write target)
+    ├── downloads/      # Browser-downloaded files
+    └── screenshots/    # Browser screenshots
+```
+
+The `openpaw init` command scaffolds this structure with starter templates. Customize the identity files in `agent/` to shape your agent's personality and purpose. Configure model, channel, and queue behavior in `config/agent.yaml`.
+
+The `data/` and `config/` directories are write-protected from agent filesystem tools. Write operations default to the `workspace/` directory unless an explicit path is provided.
+
+## In-Chat Commands
+
+Once running, agents respond to framework commands in chat:
+
+| Command | Description |
+|---------|-------------|
+| `/help` | List available commands |
+| `/status` | Show model, context usage, tasks, and token usage |
+| `/new` | Archive conversation and start fresh |
+| `/compact` | Summarize, archive, and continue with summary |
+| `/model <provider:model>` | Switch LLM model at runtime |
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) -- Installation, first workspace, and troubleshooting
+- [Concepts](docs/concepts.md) -- How workspaces, scheduling, queues, and tools fit together
+- [Configuration](docs/configuration.md) -- Global and per-workspace configuration reference
+- [Workspaces](docs/workspaces.md) -- Workspace structure, identity files, and custom tools
+- [Scheduling](docs/scheduling.md) -- Cron jobs, heartbeats, and dynamic scheduling
+- [Built-ins](docs/builtins.md) -- Web search, browser automation, email, voice, sub-agents, and more
+- [Channels](docs/channels.md) -- Channel adapters and access control
+- [Queue System](docs/queue-system.md) -- Queue modes and message handling
+- [Architecture](docs/architecture.md) -- System design, data flows, and architectural decisions
+
+## Contributing
+
+Development follows a GitFlow branching model:
+
+- **`main`** -- Stable releases only. Protected branch, requires CI to pass.
+- **`develop`** -- Integration branch. Feature and bugfix PRs target `develop`.
+- **Feature branches** -- Branch from `develop` as `feature/`, `bugfix/`, `docs/`, or `chore/`.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide.
+
+## AI Code Review
+
+All pull requests are automatically reviewed by GPT-4o via [ai-code-review](https://github.com/AleksandrFurmenkovOfficial/ai-code-review). The AI checks for code quality, security issues, performance concerns, and maintainability.
+
+Reviews run on every PR open and update. Results are posted as inline comments on the pull request.
+
+## Prerequisites
+
+- Python 3.11+
+- [Poetry 2.0+](https://python-poetry.org/docs/#installation)
+- At least one channel bot token: [Telegram](https://core.telegram.org/bots#botfather) or [Discord](https://discord.com/developers/applications)
+- At least one model provider API key (Anthropic, OpenAI, or AWS credentials for Bedrock)
+
+## License
+
+[PolyForm Noncommercial 1.0.0](LICENSE)
+

openpaw_ai-0.4.0/README.md

@@ -0,0 +1,197 @@
+<div align="center">
+  <img src="docs/assets/images/logo.png" alt="OpenPaw" width="400">
+  <p><strong>A Friendly <a href="https://langchain-ai.github.io/langgraph/">LangChain/LangGraph</a> Multi-Agent Runner</strong></p>
+  <p>
+    <a href="https://github.com/johnsosoka/OpenPaw/actions/workflows/ci.yml"><img src="https://github.com/johnsosoka/OpenPaw/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+    <a href="https://github.com/johnsosoka/OpenPaw/actions/workflows/docs.yml"><img src="https://github.com/johnsosoka/OpenPaw/actions/workflows/docs.yml/badge.svg?branch=main" alt="Docs"></a>
+    <img src="https://github.com/johnsosoka/OpenPaw/actions/workflows/ai-code-review.yml/badge.svg" alt="AI Code Review">
+    <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+">
+    <img src="https://img.shields.io/badge/license-PolyForm%20Noncommercial-green" alt="License">
+  </p>
+</div>
+
+---
+
+> **Pre-1.0 Release (0.4.0)** — OpenPaw is actively developed. The API may evolve as we work towards a stable 1.0.0 release. Contributions and feedback are welcome.
+
+OpenPaw gives each agent its own workspace -- personality files, custom tools, scheduled tasks -- then gets out of the way. It handles the orchestration so you can focus on what your agents actually do.
+
+Agents can ingest documents, browse the web, search the internet, and manage their own files -- making them well-suited for research, information processing, and long-running autonomous workflows. Give them a schedule and they'll check in on their own.
+
+> **[Read the full documentation](https://johnsosoka.github.io/OpenPaw/)**
+
+## Highlights
+
+**First Class Document processing** -- Docling OCR/ICR turns scanned PDFs, DOCX, and PPTX into markdown automatically. Whisper transcribes voice messages on arrival.
+
+**Drop-in custom tools** -- Write a `@tool` function, put it in `agent/tools/`, restart. Your agent picks it up with zero wiring.
+
+**Multi-agent spawning** -- Agents spin up background workers for parallel tasks with full lifecycle tracking and result collection.
+
+**Dynamic tool assignment** -- Spawned sub-agents can be given a tailored tool loadout via allow/deny lists, so each worker gets only the capabilities it needs.
+
+**Cron scheduling and heartbeats** -- Recurring jobs, one-shot timers, proactive check-ins. Agents can even self-schedule follow-ups at runtime.
+
+**Browser automation** -- Playwright-driven web interaction via accessibility tree. Agents reference page elements by number, not CSS selectors.
+
+**Email integration** -- Send and receive email via Gmail with safe-by-default recipient policies. Read inbox, search, reply with threading, and manage attachments.
+
+**Deep research** -- Integrate with a self-hosted GPT-Researcher instance for multi-source research reports with citations. Agents submit queries via WebSocket and receive comprehensive markdown reports.
+
+**Approval gates** -- Human-in-the-loop authorization for dangerous operations, with configurable timeouts and channel-native UI.
+
+**Multi-channel support** -- Connect agents to Telegram, Discord, or both simultaneously. Trigger-based activation lets agents respond to @mentions, keyword triggers, or both in group chats. On-demand context fetch gives agents awareness of recent channel history when triggered.
+
+**Session management** -- Conversations auto-reset after inactivity (default 3 hours). Auto-compact rotates context when the window fills. Persistent channel logs give agents searchable message history.
+
+**Workspace isolation** -- Each agent gets its own SOUL.md personality, tools directory, conversation history, channels, and sandboxed filesystem.
+
+**Multi-provider LLM support** -- Anthropic, OpenAI, AWS Bedrock, xAI, and any OpenAI-compatible endpoint. Switch models at runtime with `/model`.
+
+**Memory and observability** -- Vector search for semantic recall, conversation archiving to markdown and JSON, and session logs for every cron, heartbeat, and sub-agent run. Full visibility into what your agents are doing and thinking.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+pip install openpaw-ai
+```
+
+For development from source:
+
+```bash
+git clone https://github.com/johnsosoka/OpenPaw.git
+cd OpenPaw
+poetry install
+```
+
+### 2. Scaffold a workspace
+
+```bash
+poetry run openpaw init my_agent \
+  --model anthropic:claude-sonnet-4-20250514 \
+  --channel telegram
+```
+
+### 3. Configure
+
+```bash
+cp config.example.yaml config.yaml
+```
+
+Add your API keys to `agent_workspaces/my_agent/config/.env`:
+
+```bash
+ANTHROPIC_API_KEY=your-key-here
+TELEGRAM_BOT_TOKEN=your-token-here
+```
+
+### 4. Run
+
+```bash
+poetry run openpaw -c config.yaml -w my_agent
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `openpaw init <name>` | Scaffold a new agent workspace |
+| `openpaw init <name> --model <provider:model>` | Scaffold with a pre-configured model |
+| `openpaw init <name> --channel telegram` | Scaffold with channel pre-configured (`telegram` or `discord`) |
+| `openpaw list` | List available workspaces |
+| `openpaw -c config.yaml -w <name>` | Run a single workspace |
+| `openpaw -c config.yaml -w name1,name2` | Run multiple workspaces |
+| `openpaw -c config.yaml --all` | Run all discovered workspaces |
+| `openpaw -c config.yaml -w <name> -v` | Run with verbose logging |
+
+All commands should be prefixed with `poetry run` when running from the project directory.
+
+## Agent Workspace Structure
+
+Each workspace lives under `agent_workspaces/<name>/` and is organized into five directories:
+
+```
+agent_workspaces/my_agent/
+├── agent/              # Identity and extensions
+│   ├── AGENT.md        # Capabilities and behavior guidelines
+│   ├── USER.md         # User context and preferences
+│   ├── SOUL.md         # Core personality and values
+│   ├── HEARTBEAT.md    # Session state scratchpad (agent-writable)
+│   ├── skills/         # Skill directories (SKILL.md format)
+│   ├── team/           # Spawn profiles (sub-agent personas)
+│   └── tools/          # Custom LangChain @tool functions
+├── config/             # Configuration (write-protected)
+│   ├── agent.yaml      # Per-workspace settings (model, channel, queue)
+│   ├── .env            # API keys and secrets
+│   └── crons/          # Scheduled task definitions
+├── .openpaw/           # Framework internals (write-protected)
+│   ├── conversations.db  # AsyncSqliteSaver checkpoint database
+│   ├── sessions.json     # Session/conversation thread state
+│   ├── token_usage.jsonl # Token usage metrics (append-only)
+│   └── subagents.yaml    # Sub-agent requests and results
+├── memory/             # Archived conversations and session logs
+│   ├── conversations/  # Conversation exports (markdown + JSON)
+│   └── logs/           # Session logs and channel history
+│       ├── channel/    # Persistent channel message logs (JSONL)
+│       └── sessions/   # Heartbeat, cron, and sub-agent session logs
+└── workspace/          # Agent work area (default write target)
+    ├── downloads/      # Browser-downloaded files
+    └── screenshots/    # Browser screenshots
+```
+
+The `openpaw init` command scaffolds this structure with starter templates. Customize the identity files in `agent/` to shape your agent's personality and purpose. Configure model, channel, and queue behavior in `config/agent.yaml`.
+
+The `data/` and `config/` directories are write-protected from agent filesystem tools. Write operations default to the `workspace/` directory unless an explicit path is provided.
+
+## In-Chat Commands
+
+Once running, agents respond to framework commands in chat:
+
+| Command | Description |
+|---------|-------------|
+| `/help` | List available commands |
+| `/status` | Show model, context usage, tasks, and token usage |
+| `/new` | Archive conversation and start fresh |
+| `/compact` | Summarize, archive, and continue with summary |
+| `/model <provider:model>` | Switch LLM model at runtime |
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) -- Installation, first workspace, and troubleshooting
+- [Concepts](docs/concepts.md) -- How workspaces, scheduling, queues, and tools fit together
+- [Configuration](docs/configuration.md) -- Global and per-workspace configuration reference
+- [Workspaces](docs/workspaces.md) -- Workspace structure, identity files, and custom tools
+- [Scheduling](docs/scheduling.md) -- Cron jobs, heartbeats, and dynamic scheduling
+- [Built-ins](docs/builtins.md) -- Web search, browser automation, email, voice, sub-agents, and more
+- [Channels](docs/channels.md) -- Channel adapters and access control
+- [Queue System](docs/queue-system.md) -- Queue modes and message handling
+- [Architecture](docs/architecture.md) -- System design, data flows, and architectural decisions
+
+## Contributing
+
+Development follows a GitFlow branching model:
+
+- **`main`** -- Stable releases only. Protected branch, requires CI to pass.
+- **`develop`** -- Integration branch. Feature and bugfix PRs target `develop`.
+- **Feature branches** -- Branch from `develop` as `feature/`, `bugfix/`, `docs/`, or `chore/`.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide.
+
+## AI Code Review
+
+All pull requests are automatically reviewed by GPT-4o via [ai-code-review](https://github.com/AleksandrFurmenkovOfficial/ai-code-review). The AI checks for code quality, security issues, performance concerns, and maintainability.
+
+Reviews run on every PR open and update. Results are posted as inline comments on the pull request.
+
+## Prerequisites
+
+- Python 3.11+
+- [Poetry 2.0+](https://python-poetry.org/docs/#installation)
+- At least one channel bot token: [Telegram](https://core.telegram.org/bots#botfather) or [Discord](https://discord.com/developers/applications)
+- At least one model provider API key (Anthropic, OpenAI, or AWS credentials for Bedrock)
+
+## License
+
+[PolyForm Noncommercial 1.0.0](LICENSE)

openpaw_ai-0.4.0/openpaw/__init__.py

@@ -0,0 +1,9 @@
+"""OpenPaw - Multi-Channel AI Agent Framework built on LangGraph.
+
+Each agent runs in an isolated workspace with its own identity, tools,
+conversation history, and scheduled tasks. Supports Telegram, Discord, and
+stdio channels out of the box.
+"""
+
+__version__ = "0.4.0"
+__all__ = ["__version__"]

openpaw_ai-0.4.0/openpaw/agent/__init__.py

@@ -0,0 +1,20 @@
+"""Agent execution and lifecycle management.
+
+This package consolidates agent-related functionality:
+- AgentRunner: LangGraph agent with workspace integration
+- Metrics: Token usage tracking and logging
+- Middleware: Tool execution middleware (queue-aware, approval, LLM hooks)
+- Tools: Sandboxed filesystem tools for workspace access
+"""
+
+from openpaw.agent.metrics import InvocationMetrics, TokenUsageLogger, TokenUsageReader
+from openpaw.agent.response_processor import ResponseProcessor
+from openpaw.agent.runner import AgentRunner
+
+__all__ = [
+    "AgentRunner",
+    "InvocationMetrics",
+    "ResponseProcessor",
+    "TokenUsageLogger",
+    "TokenUsageReader",
+]