octo-agent 0.11.2

data/docs/ui2-architecture.md

@@ -0,0 +1,124 @@
+# UI2 Architecture
+
+## Core Principle
+**Strict Layering**: UI layer must NOT directly access Agent layer. Use callbacks for communication.
+
+## Component Hierarchy
+```
+UIController (single external interface)
+  ├── LayoutManager (layout coordination)
+  │   ├── OutputArea (output display)
+  │   ├── InputArea (user input)
+  │   ├── TodoArea (task list)
+  │   └── InlineInput (confirmation prompt)
+  └── Callbacks (external communication)
+      ├── on_input -> CLI handles input
+      ├── on_interrupt -> CLI handles interruption
+      └── on_mode_toggle -> CLI handles mode change
+```
+
+## Data Flow
+
+### Agent → UI: One-way calls
+```ruby
+# Agent calls UI to display
+@ui&.show_tool_call(...)
+@ui&.append_output(...)
+@ui&.show_token_usage(...)
+```
+
+### UI → Agent: Via callbacks
+```ruby
+# ❌ Wrong: UI directly calls Agent
+agent.run(input)
+
+# ✅ Correct: Via callback
+ui_controller.on_input { |input| agent.run(input) }
+```
+
+## Common Mistakes
+
+### ❌ Directly accessing Agent in UI components
+```ruby
+# Bad example
+def toggle_mode
+  @agent.config.mode = "auto_approve"  # ❌ Violates separation
+end
+```
+
+### ✅ Notify via callback
+```ruby
+# Good example
+def toggle_mode
+  @mode_toggle_callback&.call("auto_approve")  # ✅ Proper separation
+end
+```
+
+### ❌ Using puts for logging
+```ruby
+puts "Debug info"  # ❌ Breaks UI rendering
+```
+
+### ✅ Use UIController.log
+```ruby
+ui_controller.log("Debug info")  # ✅ Displays in output area
+ui_controller.log("Warning", level: :warning)
+ui_controller.log("Error", level: :error)
+```
+
+## Logging System
+
+Use `ui_controller.log(message, level: :info)` to display debug information in the output area without breaking rendering.
+
+**Available log levels:**
+- `:debug` - Gray dimmed text
+- `:info` - Normal text with info symbol
+- `:warning` - Yellow warning text
+- `:error` - Red error text
+
+**Example:**
+```ruby
+# In UIController or components with access to UIController
+@ui_controller.log("Tool execution started", level: :debug)
+@ui_controller.log("Cache hit", level: :info)
+@ui_controller.log("Retry attempt 3/10", level: :warning)
+@ui_controller.log("Network failed", level: :error)
+```
+
+## Rendering Flow
+
+### Fixed Areas
+- **InputArea**: Fixed at bottom (hidden when InlineInput is active via `paused?`)
+- **TodoArea**: Fixed above InputArea
+
+### Scrolling Area
+- **OutputArea**: Natural scrolling, all content appended here
+
+### Thread Safety
+- All rendering protected by `@render_mutex`
+- Never call render methods outside LayoutManager
+
+## Key Methods
+
+### Display Methods (Agent → UI)
+- `append_output(content)` - Add content to output area
+- `update_sessionbar(tasks:, cost:)` - Update session bar
+- `show_token_usage(token_data)` - Display token statistics
+- `show_tool_call(name, args)` - Display tool execution
+- `request_confirmation(message)` - Blocking user confirmation
+
+### Callback Registration (CLI sets these)
+- `on_input { |text, images| ... }` - Handle user input
+- `on_interrupt { |input_was_empty:| ... }` - Handle Ctrl+C
+- `on_mode_toggle { |new_mode| ... }` - Handle Shift+Tab
+
+### Logging (Use instead of puts)
+- `log(message, level: :info)` - Display debug/info in output
+
+## Best Practices
+
+1. **Never bypass UIController** - All UI updates go through UIController
+2. **Use callbacks for upward communication** - UI notifies CLI/Agent via callbacks
+3. **Log via UIController** - Never use `puts` or `print` directly
+4. **Check paused state** - Don't render InputArea when InlineInput is active
+5. **Trust the render flow** - Let LayoutManager handle rendering coordination

data/homebrew/README.md

@@ -0,0 +1,96 @@
+# Homebrew Formula for Octo
+
+This directory contains the Homebrew formula for Octo.
+
+## For Maintainers: Publishing to Homebrew Tap
+
+### One-time Setup
+
+1. Create a GitHub repository named `homebrew-octo` (must start with `homebrew-`)
+2. Push this formula to the repository
+
+```bash
+# In your GitHub account, create: homebrew-octo
+git clone https://github.com/YOUR_USERNAME/homebrew-octo.git
+cd homebrew-octo
+cp /path/to/octo/homebrew/octo.rb ./Formula/octo.rb
+git add Formula/octo.rb
+git commit -m "Add octo formula"
+git push origin main
+```
+
+### Update Formula for New Release
+
+When you release a new version:
+
+1. Download the new gem and calculate SHA256:
+```bash
+VERSION=0.6.1
+wget https://rubygems.org/downloads/octo-${VERSION}.gem
+shasum -a 256 octo-${VERSION}.gem
+```
+
+2. Update the formula in `homebrew-octo` repository:
+- Update `url` with new version
+- Update `sha256` with calculated hash
+- Commit and push
+
+3. Users can then upgrade:
+```bash
+brew update
+brew upgrade octo
+```
+
+## For Users: Installation
+
+```bash
+# Add the tap (one-time)
+brew tap YOUR_USERNAME/octo
+
+# Install
+brew install octo
+
+# Or in one command
+brew install YOUR_USERNAME/octo/octo
+```
+
+## Testing the Formula Locally
+
+```bash
+# Install from local formula
+brew install --build-from-source ./homebrew/octo.rb
+
+# Or test without installing
+brew test ./homebrew/octo.rb
+```
+
+## Automation Script
+
+For easier updates, use this script:
+
+```bash
+#!/bin/bash
+# update_formula.sh
+
+VERSION=$1
+if [ -z "$VERSION" ]; then
+  echo "Usage: ./update_formula.sh VERSION"
+  exit 1
+fi
+
+# Download gem
+wget https://rubygems.org/downloads/octo-${VERSION}.gem -O /tmp/octo.gem
+
+# Calculate SHA256
+SHA256=$(shasum -a 256 /tmp/octo.gem | cut -d' ' -f1)
+
+# Update formula
+sed -i '' "s|url \".*\"|url \"https://rubygems.org/downloads/octo-${VERSION}.gem\"|" octo.rb
+sed -i '' "s|sha256 \".*\"|sha256 \"${SHA256}\"|" octo.rb
+
+echo "Formula updated to version ${VERSION}"
+echo "SHA256: ${SHA256}"
+echo "Don't forget to commit and push to homebrew-octo repository!"
+
+rm /tmp/octo.gem
+```

data/homebrew/openocto.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class Openocto < Formula
+  desc "Command-line interface for AI models with autonomous agent capabilities"
+  homepage "https://github.com/octo-ai/octo"
+  url "https://rubygems.org/downloads/octo-0.6.1.gem"
+  sha256 "" # Will be updated when gem is published
+  license "MIT"
+
+  depends_on "ruby@3.3"
+
+  def install
+    ENV["GEM_HOME"] = libexec
+    system "gem", "install", cached_download, "--no-document"
+    
+    # Create wrapper scripts
+    (bin/"octo").write_env_script libexec/"bin/octo", GEM_HOME: ENV["GEM_HOME"]
+    (bin/"octo").write_env_script libexec/"bin/octo", GEM_HOME: ENV["GEM_HOME"]
+  end
+
+  test do
+    assert_match "octo version #{version}", shell_output("#{bin}/octo version")
+  end
+end

data/lib/octo/agent/hook_manager.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Octo
+  class HookManager
+    HOOK_EVENTS = [
+      :before_tool_use,
+      :after_tool_use,
+      :on_tool_error,
+      :on_start,
+      :on_complete,
+      :on_iteration,
+      :session_rollback
+    ].freeze
+
+    def initialize
+      @hooks = Hash.new { |h, k| h[k] = [] }
+    end
+
+    def add(event, &block)
+      validate_event!(event)
+      @hooks[event] << block
+    end
+
+    def trigger(event, *args)
+      validate_event!(event)
+      result = { action: :allow }
+
+      @hooks[event].each do |hook|
+        begin
+          hook_result = hook.call(*args)
+          result.merge!(hook_result) if hook_result.is_a?(Hash)
+        rescue StandardError => e
+          # Log error but don't fail
+          Octo::Logger.error("Hook error", event: event, error: e)
+        end
+      end
+
+      result
+    end
+
+    def has_hooks?(event)
+      @hooks[event].any?
+    end
+
+    def clear(event = nil)
+      if event
+        validate_event!(event)
+        @hooks[event].clear
+      else
+        @hooks.clear
+      end
+    end
+
+
+    def validate_event!(event)
+      return if HOOK_EVENTS.include?(event)
+
+      raise ArgumentError, "Invalid hook event: #{event}. Must be one of #{HOOK_EVENTS.join(', ')}"
+    end
+  end
+end