octo-agent 0.11.2

data/docs/billing-system.md

@@ -0,0 +1,318 @@
+# Billing System
+
+## Overview
+
+The Billing System provides persistent tracking of API usage and costs across all
+sessions. It records every LLM API call with token counts and calculated costs,
+storing them in monthly JSONL files for easy querying and analysis.
+
+## Design Principles
+
+- **Non-blocking** — Billing persistence is fire-and-forget; failures never interrupt agent flow
+- **Minimal footprint** — JSONL format, one file per month, no database dependency
+- **Privacy-first** — Data stored locally in `~/.octo/billing/`, never uploaded
+- **Accurate costing** — Uses the same `ModelPricing` module as real-time display
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Agent                                   │
+│  CostTracker module                                             │
+│    └── track_cost()                                             │
+│          ├── Calculate cost (ModelPricing)                      │
+│          ├── Update UI (real-time)                              │
+│          └── persist_billing_record() ──────┐                   │
+└─────────────────────────────────────────────┼───────────────────┘
+                                              │
+                                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Billing Module                               │
+│  lib/octo/billing/                                            │
+│    ├── billing_record.rb   (data structure)                     │
+│    └── billing_store.rb    (JSONL persistence)                  │
+└─────────────────────────────────────────────────────────────────┘
+                                              │
+                                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Storage                                      │
+│  ~/.octo/billing/                                             │
+│    ├── 2026-05.jsonl                                            │
+│    ├── 2026-04.jsonl                                            │
+│    └── ...                                                      │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Components
+
+### BillingRecord (`lib/octo/billing/billing_record.rb`)
+
+A Struct representing a single API call:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | String | UUID, auto-generated |
+| `session_id` | String | Associated session |
+| `timestamp` | Time | When the call was made |
+| `model` | String | Model name (e.g., "claude-sonnet-4.5") |
+| `prompt_tokens` | Integer | Input tokens |
+| `completion_tokens` | Integer | Output tokens |
+| `cache_read_tokens` | Integer | Tokens read from cache |
+| `cache_write_tokens` | Integer | Tokens written to cache |
+| `cost_usd` | Float | Calculated cost in USD |
+| `cost_source` | Symbol | `:api`, `:price`, or `:estimated` |
+
+### BillingStore (`lib/octo/billing/billing_store.rb`)
+
+Handles persistence and querying:
+
+```ruby
+store = Octo::Billing::BillingStore.new
+
+# Append a record
+store.append(record)
+
+# Query with filters
+records = store.query(from: 1.week.ago, model: "claude-sonnet-4.5", limit: 100)
+
+# Get summary statistics
+summary = store.summary(period: :month)
+# => { total_cost: 12.34, total_tokens: 500000, by_model: {...}, ... }
+
+# Daily breakdown for charts
+daily = store.daily_breakdown(days: 30)
+# => [{ date: "2026-05-01", cost: 1.23, tokens: 50000, requests: 42 }, ...]
+```
+
+---
+
+## Storage Format
+
+Records are stored as JSON Lines (one JSON object per line):
+
+```jsonl
+{"id":"abc123","session_id":"def456","timestamp":"2026-05-22T15:30:00+08:00","model":"claude-sonnet-4.5","prompt_tokens":1500,"completion_tokens":500,"cache_read_tokens":1000,"cache_write_tokens":0,"cost_usd":0.0045,"cost_source":"price"}
+{"id":"abc124","session_id":"def456","timestamp":"2026-05-22T15:31:00+08:00","model":"claude-sonnet-4.5","prompt_tokens":2000,"completion_tokens":800,"cache_read_tokens":1500,"cache_write_tokens":0,"cost_usd":0.0052,"cost_source":"price"}
+```
+
+**Why JSONL?**
+- Append-only writes (no file locking needed)
+- Easy to parse line-by-line (memory efficient)
+- Human-readable for debugging
+- Simple monthly rotation
+
+---
+
+## API Endpoints
+
+### GET /api/billing/summary
+
+Returns aggregated statistics for a time period.
+
+**Query Parameters:**
+- `period` — `day`, `week`, `month`, `year`, or `all` (default: `month`)
+
+**Response:**
+```json
+{
+  "period": "month",
+  "from": "2026-05-01T00:00:00+08:00",
+  "to": "2026-05-22T15:30:00+08:00",
+  "total_cost": 12.3456,
+  "total_tokens": 500000,
+  "prompt_tokens": 350000,
+  "completion_tokens": 150000,
+  "cache_read_tokens": 200000,
+  "cache_write_tokens": 50000,
+  "by_model": {
+    "claude-sonnet-4.5": { "cost": 10.00, "requests": 100 },
+    "deepseek-v4-flash": { "cost": 2.34, "requests": 50 }
+  },
+  "by_day": {
+    "2026-05-22": 1.23,
+    "2026-05-21": 2.34
+  },
+  "record_count": 150
+}
+```
+
+### GET /api/billing/daily
+
+Returns daily cost breakdown for charting.
+
+**Query Parameters:**
+- `days` — Number of days (default: 30, max: 90)
+
+**Response:**
+```json
+{
+  "days": [
+    { "date": "2026-05-22", "cost": 1.2345, "tokens": 50000, "requests": 42 },
+    { "date": "2026-05-21", "cost": 2.3456, "tokens": 80000, "requests": 65 }
+  ]
+}
+```
+
+### GET /api/billing/records
+
+Returns raw billing records.
+
+**Query Parameters:**
+- `limit` — Max records (default: 100, max: 500)
+- `model` — Filter by model name
+- `session_id` — Filter by session ID
+
+**Response:**
+```json
+{
+  "records": [
+    { "id": "...", "timestamp": "...", "model": "...", "cost_usd": 0.01, ... }
+  ],
+  "count": 100
+}
+```
+
+---
+
+## CLI Command
+
+```bash
+# Show current month's billing
+octo billing
+
+# Show specific period
+octo billing --period week
+octo billing --period day
+octo billing --period all
+
+# Output as JSON (for scripting)
+octo billing --json
+```
+
+**Sample Output:**
+```
+📊 Billing Summary (month)
+──────────────────────────────────────────────────
+
+  💰 Total Cost:       $12.3456
+  📝 Total Tokens:     500,000
+  📥 Prompt Tokens:    350,000
+  📤 Completion:       150,000
+  🗄️  Cache Read:       200,000
+  📝 Cache Write:      50,000
+  🔢 API Requests:     150
+
+📈 By Model:
+──────────────────────────────────────────────────
+  claude-sonnet-4.5
+    Cost: $10.0000  |  Requests: 100
+  deepseek-v4-flash
+    Cost: $2.3456  |  Requests: 50
+
+📅 Recent Daily Usage:
+──────────────────────────────────────────────────
+  2026-05-22  $1.2345  ████████████
+  2026-05-21  $2.3456  ████████████████████████
+
+──────────────────────────────────────────────────
+  Data stored in: ~/.octo/billing/
+```
+
+---
+
+## Web UI
+
+The Billing panel is accessible from the sidebar under "My Data":
+
+- **Summary cards** — Total cost, tokens, API requests
+- **Token breakdown** — Prompt, completion, cache read/write
+- **By Model table** — Cost and request count per model
+- **Daily chart** — Visual bar chart of recent usage
+- **Period selector** — Filter by day/week/month/year/all
+
+---
+
+## Currency Settings
+
+The Web UI supports multiple currencies for cost display:
+
+| Currency | Symbol | Exchange Rate |
+|----------|--------|---------------|
+| USD | $ | 1.0 (base) |
+| CNY | ¥ | 6.7944 |
+
+### Configuration
+
+1. Go to **Settings** page
+2. Find the **Currency** section
+3. Select `$ USD` or `¥ CNY`
+
+### Scope
+
+Currency settings apply to:
+- Billing panel (total cost, model costs, daily chart)
+- Session info bar (top cost display)
+- Token usage lines (per-API-call cost)
+- Task completion messages
+
+**Note:** CLI always displays costs in USD (API's native currency).
+
+### Implementation
+
+Currency preference is stored in browser `localStorage` under key `octo-currency`.
+
+```javascript
+// Access currency utilities from Billing module
+Billing.getCurrency()       // "USD" or "CNY"
+Billing.getCurrencySymbol() // "$" or "¥"
+Billing.convertCost(usd)    // Convert USD to selected currency
+```
+
+---
+
+## Integration with CostTracker
+
+The billing system hooks into `Agent::CostTracker#track_cost`:
+
+```ruby
+def track_cost(usage, raw_api_usage: nil)
+  # ... existing cost calculation ...
+  
+  # Persist billing record (skip for subagents to avoid double-counting)
+  unless @is_subagent
+    persist_billing_record(usage, iteration_cost)
+  end
+  
+  token_data
+end
+```
+
+**Key behaviors:**
+- Subagent costs are NOT recorded separately (parent agent merges them)
+- Unknown model costs (nil) are skipped
+- Persistence failures are logged but never raise
+
+---
+
+## Data Retention
+
+- Records are stored indefinitely by default
+- Monthly files can be manually deleted from `~/.octo/billing/`
+- Future: `BillingStore#cleanup(before: 1.year.ago)` for automated retention
+
+---
+
+## Future Enhancements
+
+- [ ] Export to CSV/JSON
+- [ ] Budget alerts (daily/monthly limits)
+- [ ] Cost comparison across models
+- [ ] Session-level cost breakdown in UI
+- [x] i18n support for billing labels (English/Chinese)
+- [x] Currency settings (USD/CNY)
+- [ ] Dynamic exchange rate updates
+- [ ] More currency options (EUR, JPY, etc.)

data/docs/channel-architecture.md

@@ -0,0 +1,235 @@
+# Channel Architecture
+
+## Overview
+
+Channel is a feature that bridges Octo's Server Sessions to IM platforms
+(Feishu, WeCom, DingTalk, etc.). It reuses the existing Agent + SessionRegistry
+infrastructure — the Agent knows nothing about IM; the Channel layer is purely
+a transport adapter.
+
+## Design Principles
+
+- **Zero Agent intrusion** — Agent only speaks `UIInterface`; swap the controller, get IM output
+- **Reuse SessionRegistry** — IM chats resolve to the same `SessionRegistry` sessions as Web UI
+- **WebSocket long connection** — No public domain required; adapters hold a persistent WSS connection to the IM platform
+- **One platform = 2 threads** — read loop thread + ping/heartbeat thread (constant, small footprint)
+
+---
+
+## Layer Diagram
+
+```
+IM Platforms (Feishu / WeCom / DingTalk)
+      │  WebSocket long connection (wss://)
+      ▼
+┌─────────────────────────────────────┐
+│       Channel Adapter Layer         │
+│  Feishu::Adapter                    │
+│    ├── WSClient   (read loop + ping) │
+│    ├── Bot        (send API)         │
+│    └── MessageParser                │
+│  Wecom::Adapter                     │
+│    └── WSClient   (read loop + ping) │
+│  (future) Dingtalk::Adapter         │
+└──────────────┬──────────────────────┘
+               │ standardized event Hash
+               ▼
+┌─────────────────────────────────────┐
+│          ChannelManager             │
+│  • Owns adapter threads             │
+│  • Routes inbound event →           │
+│    ChannelBinding → session_id      │
+│  • Calls agent.run in Thread.new    │
+└──────────────┬──────────────────────┘
+               │
+       ┌───────┴────────┐
+       ▼                ▼
+SessionRegistry    ChannelUIController
+(existing)         (implements UIInterface)
+       │                │
+       ▼                ▼
+    Agent            IM Platform reply
+  (unchanged)       via adapter.send_text
+```
+
+---
+
+## File Structure
+
+```
+lib/octo/channel/
+├── adapters/
+│   ├── base.rb                  # Adapter abstract base + registry
+│   ├── feishu/
+│   │   ├── adapter.rb           # Feishu::Adapter < Base
+│   │   ├── bot.rb               # HTTP send API (token cache, Markdown/card)
+│   │   ├── message_parser.rb    # Raw WS event → standardized Hash
+│   │   └── ws_client.rb         # Feishu protobuf WS long connection
+│   └── wecom/
+│       ├── adapter.rb           # Wecom::Adapter < Base
+│       └── ws_client.rb         # WeCom JSON WS long connection
+├── channel_message.rb           # Struct: standardized inbound message
+├── channel_binding.rb           # (platform, user_id) → session_id mapping
+├── channel_ui_controller.rb     # UIInterface impl — pushes events to IM
+└── channel_manager.rb           # Lifecycle: start/stop adapters, route messages
+lib/octo/channel.rb            # Top-level require entry point
+```
+
+---
+
+## Standardized Inbound Event
+
+All adapters yield the same Hash shape to `ChannelManager`:
+
+```ruby
+{
+  platform:   :feishu,          # Symbol
+  chat_id:    "oc_xxx",         # String — IM chat/group identifier
+  user_id:    "ou_xxx",         # String — IM user identifier
+  text:       "deploy now",     # String — cleaned user text
+  message_id: "om_xxx",         # String — for threading / update
+  timestamp:  Time,             # Time object
+  chat_type:  :direct | :group, # Symbol
+  raw:        { ... }           # Original platform payload
+}
+```
+
+---
+
+## Adapter Interface (Base)
+
+```ruby
+class Adapters::Base
+  def self.platform_id → Symbol
+  def self.platform_config(raw_config) → Hash   # symbol-keyed
+  def self.env_keys → Array<String>             # for config serialization
+
+  def start(&on_message)   # blocks; yields event Hash per inbound message
+  def stop                 # graceful shutdown
+  def send_text(chat_id, text, reply_to: nil) → Hash
+  def update_message(chat_id, message_id, text) → Boolean
+  def supports_message_updates? → Boolean
+  def validate_config(config) → Array<String>   # error messages
+end
+```
+
+---
+
+## ChannelManager
+
+```ruby
+class ChannelManager
+  def initialize(session_registry:, session_builder:, channel_config:, agent_config:)
+
+  def start   # Thread.new per enabled platform adapter
+  def stop    # kills all adapter threads gracefully
+
+  private
+
+  def route_message(adapter, event)
+    session_id = @binding.resolve_or_create(event, session_builder: @session_builder)
+    ui         = ChannelUIController.new(event, adapter)
+    Thread.new { run_agent(session_id, event[:text], ui) }
+  end
+end
+```
+
+---
+
+## ChannelBinding
+
+Maps `(platform, user_id)` → `session_id`. Persisted to `~/.octo/channel_bindings.yml`.
+
+Binding modes (configurable per platform):
+
+| Mode | Key | Description |
+|------|-----|-------------|
+| `user` | `(platform, user_id)` | Each IM user gets their own session (default) |
+| `chat` | `(platform, chat_id)` | Whole group shares one session |
+
+---
+
+## ChannelUIController
+
+Implements `UIInterface`. Key behaviours:
+
+- `show_assistant_message` → `adapter.send_text(chat_id, content)`
+- `show_tool_call` → buffers as `⚙️ \`tool summary\`` (flushed on next message)
+- `show_progress` → `adapter.update_message(...)` if `supports_message_updates?`
+- `show_complete` → sends `✅ Complete • N iterations • $cost`
+- `request_confirmation` → **not supported in IM** (returns auto-approved / raises)
+
+---
+
+## Thread Model
+
+```
+Main thread  (WEBrick server.start — blocks)
+├── WEBrick request threads    (existing)
+├── Agent task threads         (existing, per task)
+├── Scheduler thread           (existing, octo-scheduler)
+└── ChannelManager
+    ├── feishu-adapter thread  (WSClient read loop, constant)
+    │   └── feishu-ping thread (heartbeat, 90s)
+    └── wecom-adapter thread   (WSClient read loop, constant)
+        └── wecom-ping thread  (heartbeat, 30s)
+```
+
+Per enabled platform: **2 constant threads**. Agent task threads are spawned
+on demand (same as Web UI path) and exit when done.
+
+---
+
+## Configuration
+
+Channel credentials live in `~/.octo/channels.yml` (managed by `ChannelConfig`
+which already exists in main branch):
+
+```yaml
+channels:
+  feishu:
+    enabled: true
+    app_id: cli_xxx
+    app_secret: xxx
+    allowed_users:
+      - ou_xxx
+  wecom:
+    enabled: false
+    bot_id: xxx
+    secret: xxx
+```
+
+`ChannelManager` reads this via `ChannelConfig#platform_config(platform)`.
+
+---
+
+## Integration with HttpServer
+
+```ruby
+# HttpServer#initialize
+@channel_manager = ChannelManager.new(
+  session_registry: @registry,
+  session_builder:  method(:build_session),
+  channel_config:   Octo::ChannelConfig.load,
+  agent_config:     @agent_config
+)
+
+# HttpServer#start  (after scheduler.start)
+@channel_manager.start
+```
+
+`ChannelManager#start` is non-blocking (spawns threads internally),
+mirroring `Scheduler#start` behaviour.
+
+---
+
+## Future: DingTalk
+
+DingTalk also supports a WebSocket Stream mode. Adding it means:
+
+1. `lib/octo/channel/adapters/dingtalk/adapter.rb` inheriting `Base`
+2. `lib/octo/channel/adapters/dingtalk/ws_client.rb`
+3. Register: `Adapters.register(:dingtalk, Adapter)`
+4. Add credentials to `ChannelConfig`
+
+No changes needed to `ChannelManager`, `ChannelUIController`, or `ChannelBinding`.