pocketrb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 90af53988338c89d33687693fc1a57069e32851cc3c98ce9f3bd52b69b335af6
+  data.tar.gz: 4095da56b7bf3b918485e90191cb568eacd24dfdcf47bddc1845b9702ce4a547
+SHA512:
+  metadata.gz: e2a1e6398ba744257c0cde3b288c64dcb331684a52fff7e68c43ca9d9640b1b3de8edda1536d5eb2819a91b2b127bc29caebe14dd5ba606450e609b86667cb2c
+  data.tar.gz: 5010acdbbf7916b1e33392783559568cd6b74b4dd1d26d1017ca144f9b705478e15466d92fe069b966bd8dfda7473d14d8af5a3a2ee07e4db6fe21d253b69312

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# 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.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-04
+
+### Added
+
+- Initial release
+- Core infrastructure with MessageBus for async message passing
+- Multi-LLM provider support (Anthropic API, Anthropic OAuth/Max, OpenRouter, RubyLLM, ClaudeCLI)
+- Agent loop with tool execution and iteration handling
+- Session management with JSONL persistence
+- Context compaction for long conversations (40 messages / 50K tokens threshold)
+- Core tools: read_file, write_file, edit_file, list_dir, exec, web_search, web_fetch, think, plan
+- Simple JSON-based memory system with keyword matching (no external dependencies)
+- Memory tool for storing/recalling facts, preferences, and context
+- Multi-channel support: CLI, Telegram, WhatsApp (via bridge)
+- Skills system with SKILL.md files and runtime creation
+- Built-in skills: proactive, reflection
+- Planning system for complex multi-step tasks
+- Cron service for scheduled tasks
+- Job queue for long-running background commands
+- Vision support for image analysis (Claude providers)
+- Browser automation tools (Playwright integration)
+- File sending capabilities (Telegram)
+- CLI commands: chat, telegram, whatsapp, gateway, config, skills, cron, jobs
+- Configuration management with workspace and global configs
+- Persona support (separate memory from workspace)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Maciej Mensfeld
+
+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.

data/README.md

@@ -0,0 +1,456 @@
+# Pocketrb
+
+[![Gem Version](https://badge.fury.io/rb/pocketrb.svg)](https://badge.fury.io/rb/pocketrb)
+[![CI](https://github.com/mensfeld/pocketrb/actions/workflows/ci.yml/badge.svg)](https://github.com/mensfeld/pocketrb/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
+A pocket-sized Ruby AI agent framework with multi-LLM support and advanced capabilities.
+
+## Features
+
+- **Clean async architecture**: MessageBus, proper tool_use API, async processing
+- **Multi-LLM support**: Claude (API + Max/OAuth), OpenRouter, OpenAI-compatible APIs, RubyLLM
+- **Multi-channel**: CLI, Telegram, WhatsApp (via bridge)
+- **Advanced features**: Planning system, context compaction, runtime skills system
+- **Simple memory**: JSON-based memory with keyword matching (no external dependencies)
+- **Media support**: Vision (images) via Claude, document handling
+- **Scheduling**: Cron jobs for automated tasks
+- **Personas**: Separate memory and identity from workspace for portable agent personalities
+
+## Installation
+
+```bash
+gem install pocketrb
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'pocketrb'
+```
+
+## Quick Start
+
+```bash
+# Set your API key
+export ANTHROPIC_API_KEY=your-key
+
+# Initialize a workspace
+pocketrb init
+
+# Start chatting
+pocketrb chat
+```
+
+## Usage
+
+### CLI Chat
+
+```bash
+pocketrb chat [options]
+```
+
+Options:
+- `-m, --model MODEL` - Model to use (default: claude-sonnet-4-20250514)
+- `-p, --provider PROVIDER` - LLM provider (anthropic, openrouter, ruby_llm)
+- `-w, --workspace DIR` - Workspace directory for file access
+- `-M, --memory-dir DIR` - Memory/persona directory (default: same as workspace)
+- `-s, --system-prompt TEXT` - Custom system prompt
+
+### Telegram Bot
+
+```bash
+export TELEGRAM_BOT_TOKEN=your-bot-token
+pocketrb telegram --allowed-users your_username
+```
+
+Options:
+- `-t, --token TOKEN` - Bot token (or use env var)
+- `-u, --allowed-users` - Restrict access to specific usernames/IDs
+- `-w, --workspace` - File access directory
+- `-M, --memory-dir` - Persona/memory directory
+
+### WhatsApp Bot
+
+Requires the [whatsapp-web.js bridge](https://github.com/user/whatsapp-bridge) running.
+
+```bash
+pocketrb whatsapp --bridge-url ws://localhost:3001 --allowed-users +1234567890
+```
+
+### Separating Workspace from Memory (Personas)
+
+Run with full filesystem access but a specific persona's memory:
+
+```bash
+pocketrb telegram \
+  --workspace / \
+  --memory-dir ~/.pocketrb/personas/koda \
+  --token "$TELEGRAM_BOT_TOKEN" \
+  --allowed-users your_username
+```
+
+This gives the agent:
+- Full filesystem access via `--workspace /`
+- Koda's personality and memory via `--memory-dir`
+
+## Personas
+
+Personas allow you to give the agent a persistent identity and memory separate from the working directory.
+
+### Directory Structure
+
+```
+~/.pocketrb/personas/my-agent/
+├── IDENTITY.md      # Agent personality and instructions
+├── MEMORY.md        # Background knowledge and facts
+├── memory/          # Daily notes
+│   ├── 2026-02-01.md
+│   └── 2026-02-02.md
+├── skills/          # Custom skills
+└── .pocketrb/
+    ├── config.yml   # Agent-specific config
+    └── sessions/    # Conversation history
+```
+
+### IDENTITY.md
+
+Defines who the agent is. Loaded into the system prompt automatically.
+
+```markdown
+# Agent Identity
+
+## Who I Am
+
+**Name:** Assistant
+**Role:** Helpful AI assistant
+**Personality:** Friendly, direct, technically skilled
+
+## How I Work
+
+- I verify before claiming things are done
+- I explain what I'm doing when executing commands
+- I ask for clarification when requirements are unclear
+
+## Communication Style
+
+- Concise and direct
+- Technical when appropriate
+- No unnecessary pleasantries
+```
+
+### MEMORY.md
+
+Background knowledge the agent should always have access to.
+
+```markdown
+# Background Knowledge
+
+## User Information
+
+- **Name**: John
+- **Timezone**: UTC+1
+- **Preferences**: Prefers Python over JavaScript
+
+## Project Context
+
+- Working on a web scraping project
+- Database is PostgreSQL 16
+- Deployment target is AWS Lambda
+```
+
+## Skills
+
+Skills are reusable prompts that extend the agent's capabilities.
+
+### Creating Skills
+
+Create a skill in `skills/skill-name/SKILL.md`:
+
+```markdown
+---
+name: code-review
+description: Review code for quality and best practices
+triggers:
+  - review
+  - code review
+  - check this code
+metadata:
+  emoji: "🔍"
+  requires:
+    bins: []
+---
+
+# Code Review Skill
+
+When reviewing code, analyze:
+
+1. **Correctness**: Does it do what it's supposed to?
+2. **Readability**: Is the code clear and well-organized?
+3. **Performance**: Any obvious inefficiencies?
+4. **Security**: Input validation, injection risks, etc.
+5. **Edge cases**: What happens with unexpected input?
+
+Provide specific, actionable feedback with line numbers.
+```
+
+### Skill Frontmatter
+
+| Field | Description |
+|-------|-------------|
+| `name` | Skill identifier |
+| `description` | Short description shown in skill list |
+| `triggers` | Phrases that activate this skill |
+| `always` | If true, always loaded into context |
+| `metadata.emoji` | Display emoji |
+| `metadata.requires.bins` | Required binaries (e.g., `["git", "docker"]`) |
+| `metadata.os` | Supported OS (e.g., `["linux", "darwin"]`) |
+
+### Built-in Skills
+
+Pocketrb includes several built-in skills:
+
+- **github** - GitHub CLI operations (`gh pr`, `gh issue`, etc.)
+- **tmux** - Tmux session management for isolated workspaces
+- **weather** - Weather forecasts via wttr.in
+
+### Listing Skills
+
+```bash
+pocketrb skills
+```
+
+### Runtime Skill Creation
+
+The agent can create new skills at runtime using the `skill_create` tool:
+
+```
+Create a skill called "deploy" that guides deployment to production
+```
+
+## Tools
+
+### File Operations
+
+| Tool | Description |
+|------|-------------|
+| `read_file` | Read file contents with line numbers |
+| `write_file` | Write content to a file |
+| `edit_file` | Search/replace editing |
+| `list_dir` | List directory contents |
+
+### Execution
+
+| Tool | Description |
+|------|-------------|
+| `exec` | Execute shell commands (auto-backgrounds long commands) |
+| `spawn` | Spawn background subagents for parallel work |
+
+### Web
+
+| Tool | Description |
+|------|-------------|
+| `web_search` | Search the web (requires `BRAVE_API_KEY`) |
+| `web_fetch` | Fetch and extract content from URLs |
+
+### Planning & Memory
+
+| Tool | Description |
+|------|-------------|
+| `think` | Internal reasoning for complex problems |
+| `plan` | Create and manage multi-step execution plans |
+| `memory` | Store and search long-term memory |
+
+### Communication
+
+| Tool | Description |
+|------|-------------|
+| `message` | Send messages to channels (Telegram, WhatsApp) |
+
+## Providers
+
+### Anthropic (default)
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+pocketrb chat --provider anthropic
+```
+
+### Claude Max (OAuth)
+
+For Claude Max subscribers:
+
+```bash
+export ANTHROPIC_OAUTH_TOKEN=your-oauth-token
+pocketrb chat --provider anthropic
+```
+
+### OpenRouter
+
+Access multiple models:
+
+```bash
+export OPENROUTER_API_KEY=your-key
+pocketrb chat --provider openrouter --model anthropic/claude-sonnet-4
+```
+
+## Memory System
+
+Pocketrb uses a simple, dependency-free memory system:
+
+### Static Memory
+
+- **MEMORY.md** - Static background knowledge loaded into every conversation
+- **IDENTITY.md** - Agent personality and instructions
+
+### Dynamic Memory
+
+The agent can store and recall facts using the `memory` tool:
+
+**Categories:**
+- `learned` - Things the agent has learned (e.g., "deployment process")
+- `user` - User information (e.g., "timezone: UTC+1")
+- `preference` - User preferences (e.g., "coding_style: functional")
+- `context` - General context (e.g., "database: PostgreSQL 16")
+
+**Storage:**
+- Facts stored in `memory/facts.json`
+- Recent events in `memory/recent.json`
+- Simple keyword matching for relevance (no vector DB required)
+
+**Usage:**
+```
+Agent: I'll remember that your timezone is UTC+1
+[Uses memory tool: store, category: user, key: "timezone", value: "UTC+1"]
+
+User: What's my timezone?
+Agent: [Recalls from memory] Your timezone is UTC+1
+```
+
+## Scheduling
+
+### Cron Jobs
+
+Schedule recurring tasks:
+
+```bash
+# Add a job that runs every hour
+pocketrb cron add --name "hourly-check" --message "Check system status" --every 3600
+
+# Add a cron-style job (9am daily)
+pocketrb cron add --name "morning-report" --message "Generate daily report" --cron "0 9 * * *"
+
+# Add a one-time job
+pocketrb cron add --name "reminder" --message "Meeting in 10 minutes" --at "2026-02-03T14:50:00"
+
+# List jobs
+pocketrb cron list
+
+# Remove a job
+pocketrb cron remove job_id
+```
+
+
+## Gateway Mode
+
+Run all services together:
+
+```bash
+pocketrb gateway \
+  --telegram-token "$TELEGRAM_BOT_TOKEN" \
+  --telegram-users your_username \
+  --enable-cron
+```
+
+## Context Compaction
+
+Long conversations are automatically summarized to save tokens:
+
+- Triggers after 40 messages or ~50k tokens
+- Keeps last 15 messages intact
+- Summarizes older messages using the LLM
+- Falls back to basic summary if LLM fails
+
+## Configuration
+
+### Config File
+
+Located at `workspace/.pocketrb/config.yml` or `~/.pocketrb/config.yml`:
+
+```yaml
+provider: anthropic
+model: claude-sonnet-4-20250514
+max_iterations: 50
+```
+
+### Commands
+
+```bash
+pocketrb config show
+pocketrb config set model claude-opus-4-20250514
+pocketrb config get model
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ANTHROPIC_API_KEY` | Anthropic API key |
+| `ANTHROPIC_OAUTH_TOKEN` | Claude Max OAuth token |
+| `OPENROUTER_API_KEY` | OpenRouter API key |
+| `BRAVE_API_KEY` | Brave Search API key (for web_search tool) |
+| `TELEGRAM_BOT_TOKEN` | Telegram bot token |
+| `POCKETRB_PROVIDER` | Default provider (anthropic, openrouter, ruby_llm, claude_cli) |
+| `POCKETRB_MODEL` | Default model |
+| `POCKETRB_LOG_LEVEL` | Log level (debug, info, warn, error) |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Pocketrb Core                           │
+├─────────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
+│  │ MessageBus  │  │ LLMProvider │  │    Memory System        │  │
+│  │ (Async::Q)  │  │ (multi-LLM) │  │ (JSON + keyword match)  │  │
+│  └──────┬──────┘  └──────┬──────┘  └───────────┬─────────────┘  │
+│         │                │                      │                │
+│  ┌──────▼──────────────────▼──────────────────────▼─────────┐   │
+│  │                    AgentLoop                              │   │
+│  │  - Context building (identity, memory, history)           │   │
+│  │  - Tool execution via ToolRegistry                        │   │
+│  │  - Context compaction for long conversations              │   │
+│  │  - Session management (JSONL persistence)                 │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│         │                │                                       │
+│  ┌──────▼──────┐  ┌──────▼──────┐  ┌──────────────────────┐     │
+│  │ SkillLoader │  │ CronService │  │    ToolRegistry      │     │
+│  │ (SKILL.md)  │  │ (schedule)  │  │ (file, exec, web...) │     │
+│  └─────────────┘  └─────────────┘  └──────────────────────┘     │
+│         │                                                        │
+│  ┌──────▼────────────────────────────────────────────────────┐  │
+│  │                      Channels                              │  │
+│  │  CLI  │  Telegram  │  WhatsApp  │  (extensible)            │  │
+│  └───────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run specific test
+bundle exec rspec spec/unit/tools/read_file_spec.rb
+
+# Interactive console
+bundle exec irb -r ./lib/pocketrb
+```
+
+## License
+
+MIT License - see LICENSE.txt

data/exe/pocketrb

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "pocketrb"
+
+Pocketrb::CLI.start(ARGV)