pocketrb 0.1.0 → 0.3.0

data/lib/pocketrb/tools/exec.rb

@@ -4,6 +4,7 @@ require "open3"
 require "timeout"
 
 module Pocketrb
+  # Tool implementations for agent capabilities
   module Tools
     # Execute shell commands with smart timeout and background job support
     class Exec < Base
@@ -14,7 +15,9 @@ module Pocketrb
         complex: 300    # Builds, installs
       }.freeze
 
+      # Default timeout for standard commands in seconds
       DEFAULT_TIMEOUT = TIMEOUTS[:standard]
+      # Maximum output size to capture in bytes
       MAX_OUTPUT_SIZE = 100_000
 
       # Quick commands that should finish fast
@@ -29,14 +32,20 @@ module Pocketrb
         /^\[/ # test bracket syntax
       ].freeze
 
+      # Tool name
+      # @return [String]
       def name
         "exec"
       end
 
+      # Tool description
+      # @return [String]
       def description
         "Execute a shell command. Long-running commands (apt install, npm install, etc.) auto-run in background. Use for git, npm, make, and other development tools."
       end
 
+      # Parameter schema
+      # @return [Hash]
       def parameters
         {
           type: "object",
@@ -62,6 +71,12 @@ module Pocketrb
         }
       end
 
+      # Execute shell command
+      # @param command [String] Shell command to execute
+      # @param timeout [Integer, nil] Execution timeout in seconds
+      # @param working_dir [String, nil] Working directory for command
+      # @param background [Boolean, nil] Force background execution
+      # @return [String] Command output or job information
       def execute(command:, timeout: nil, working_dir: nil, background: nil)
         work_dir = resolve_working_dir(working_dir)
         return work_dir if work_dir.is_a?(String) && work_dir.start_with?("Error:")
@@ -80,10 +95,15 @@ module Pocketrb
 
       private
 
+      # Access or initialize the background job manager
+      # @return [BackgroundJobManager]
       def job_manager
         @job_manager ||= BackgroundJobManager.new(workspace: workspace)
       end
 
+      # Resolve and validate the working directory
+      # @param working_dir [String, nil] explicit directory path or nil for workspace
+      # @return [String] resolved directory path or error string
       def resolve_working_dir(working_dir)
         if working_dir
           resolved = resolve_path(working_dir)
@@ -95,6 +115,10 @@ module Pocketrb
         end
       end
 
+      # Run a command as a background job
+      # @param command [String] shell command to run
+      # @param work_dir [String] working directory
+      # @return [String] job metadata including ID and PID
       def execute_background(command, work_dir)
         Pocketrb.logger.debug("Running in background: #{command}")
 
@@ -114,6 +138,11 @@ module Pocketrb
         OUTPUT
       end
 
+      # Run a command in the foreground with timeout
+      # @param command [String] shell command to run
+      # @param work_dir [String] working directory
+      # @param explicit_timeout [Integer, nil] timeout in seconds, auto-detected if nil
+      # @return [String] command output and exit status
       def execute_foreground(command, work_dir, explicit_timeout)
         timeout = explicit_timeout || smart_timeout(command)
         timeout = [timeout, 600].min if timeout
@@ -137,6 +166,9 @@ module Pocketrb
         format_result(stdout, stderr, status)
       end
 
+      # Determine timeout based on command type
+      # @param command [String] shell command to analyze
+      # @return [Integer, nil] timeout in seconds or nil for no timeout
       def smart_timeout(command)
         return TIMEOUTS[:simple] if quick_command?(command)
         return nil if job_manager.long_running?(command)
@@ -144,12 +176,18 @@ module Pocketrb
         TIMEOUTS[:standard]
       end
 
+      # Check if command matches fast-executing patterns
+      # @param command [String] shell command to check
+      # @return [Boolean]
       def quick_command?(command)
         return false if command.nil? || command.empty?
 
         QUICK_PATTERNS.any? { |p| command.match?(p) }
       end
 
+      # Check if command matches known dangerous patterns
+      # @param command [String] shell command to check
+      # @return [Boolean]
       def dangerous_command?(command)
         dangerous_patterns = [
           %r{\brm\s+-rf\s+[/~]},
@@ -165,6 +203,11 @@ module Pocketrb
         dangerous_patterns.any? { |pattern| command.match?(pattern) }
       end
 
+      # Format command execution result for display
+      # @param stdout [String] standard output
+      # @param stderr [String] standard error
+      # @param status [Process::Status] exit status
+      # @return [String] formatted result
       def format_result(stdout, stderr, status)
         output_parts = []
 
@@ -183,6 +226,9 @@ module Pocketrb
         output_parts.join("\n\n")
       end
 
+      # Truncate output that exceeds the maximum size
+      # @param output [String] output text to truncate
+      # @return [String] truncated or original output
       def truncate_output(output)
         return output if output.length <= MAX_OUTPUT_SIZE
 

data/lib/pocketrb/tools/jobs.rb

@@ -4,14 +4,20 @@ module Pocketrb
   module Tools
     # Manage background jobs
     class Jobs < Base
+      # Tool name
+      # @return [String] Tool identifier
       def name
         "jobs"
       end
 
+      # Tool description
+      # @return [String] Human-readable description
       def description
         "Manage background jobs. List running/completed jobs, get output, or kill jobs."
       end
 
+      # Tool parameters schema
+      # @return [Hash] JSON schema for tool parameters
       def parameters
         {
           type: "object",
@@ -34,6 +40,11 @@ module Pocketrb
         }
       end
 
+      # Execute background job operation
+      # @param action [String] Action to perform (list, status, output, kill)
+      # @param job_id [String, nil] Job identifier (for status/output/kill actions)
+      # @param lines [Integer] Number of output lines to show (defaults to 50)
+      # @return [String] JSON result of operation
       def execute(action:, job_id: nil, lines: 50)
         case action
         when "list"
@@ -51,12 +62,16 @@ module Pocketrb
 
       private
 
+      # Access or initialize the background job manager
+      # @return [BackgroundJobManager]
       def job_manager
         # Use memory_dir for job storage (falls back to workspace if not set)
         storage_dir = @context[:memory_dir] || workspace
         @job_manager ||= BackgroundJobManager.new(workspace: storage_dir)
       end
 
+      # List all background jobs grouped by running/completed status
+      # @return [String] formatted job listing
       def list_jobs
         jobs = job_manager.list
 
@@ -64,8 +79,7 @@ module Pocketrb
 
         output = ["Background Jobs:\n"]
 
-        running = jobs.select { |j| j[:running] }
-        completed = jobs.reject { |j| j[:running] }
+        running, completed = jobs.partition { |j| j[:running] }
 
         if running.any?
           output << "RUNNING:"
@@ -86,6 +100,9 @@ module Pocketrb
         output.join("\n")
       end
 
+      # Get detailed status of a job
+      # @param job_id [String] job identifier
+      # @return [String] job status details or error message
       def get_status(job_id)
         return error("Job ID required") unless job_id
 
@@ -104,6 +121,10 @@ module Pocketrb
         STATUS
       end
 
+      # Get recent output from a job
+      # @param job_id [String] job identifier
+      # @param lines [Integer] number of lines to retrieve
+      # @return [String] job output or error message
       def get_output(job_id, lines)
         return error("Job ID required") unless job_id
 
@@ -113,6 +134,9 @@ module Pocketrb
         "Output (last #{lines} lines):\n#{output}"
       end
 
+      # Kill a running job
+      # @param job_id [String] job identifier
+      # @return [String] confirmation or error message
       def kill_job(job_id)
         return error("Job ID required") unless job_id
 

data/lib/pocketrb/tools/list_dir.rb

@@ -4,14 +4,20 @@ module Pocketrb
   module Tools
     # List directory contents
     class ListDir < Base
+      # Tool name
+      # @return [String]
       def name
         "list_dir"
       end
 
+      # Tool description
+      # @return [String]
       def description
         "List the contents of a directory. Shows files and subdirectories with basic metadata."
       end
 
+      # Parameter schema
+      # @return [Hash]
       def parameters
         {
           type: "object",
@@ -37,6 +43,12 @@ module Pocketrb
         }
       end
 
+      # Execute directory listing
+      # @param path [String, nil] Directory path to list (defaults to workspace root)
+      # @param pattern [String, nil] Glob pattern to filter results
+      # @param recursive [Boolean] Whether to list subdirectories recursively
+      # @param include_hidden [Boolean] Whether to include hidden files
+      # @return [String] Formatted directory listing
       def execute(path: nil, pattern: nil, recursive: false, include_hidden: false)
         resolved = path ? validate_path!(path) : workspace
 
@@ -73,6 +85,10 @@ module Pocketrb
 
       private
 
+      # Format a directory entry for display
+      # @param path [Pathname] absolute path to the entry
+      # @param relative [Pathname] path relative to workspace
+      # @return [String] formatted entry with metadata
       def format_entry(path, relative)
         if path.directory?
           "#{relative}/"
@@ -85,6 +101,9 @@ module Pocketrb
         relative.to_s
       end
 
+      # Format byte size into human-readable units
+      # @param bytes [Integer] size in bytes
+      # @return [String] formatted size string (e.g. "1.5KB")
       def format_size(bytes)
         units = %w[B KB MB GB]
         unit_index = 0

data/lib/pocketrb/tools/memory.rb

@@ -4,13 +4,19 @@ module Pocketrb
   module Tools
     # Simple memory tool - store and recall facts
     class Memory < Base
+      # Available memory actions
       ACTIONS = %w[store recall search recent stats].freeze
+      # Memory categories for organization
       CATEGORIES = %w[learned user preference context].freeze
 
+      # Tool name
+      # @return [String]
       def name
         "memory"
       end
 
+      # Tool description
+      # @return [String]
       def description
         <<~DESC.strip
           Store and recall memories. Use this to remember important facts, preferences, and learnings.
@@ -24,6 +30,8 @@ module Pocketrb
         DESC
       end
 
+      # Parameter schema
+      # @return [Hash]
       def parameters
         {
           type: "object",
@@ -55,10 +63,19 @@ module Pocketrb
         }
       end
 
+      # Check if tool is available
+      # @return [Boolean] true if memory system is initialized
       def available?
         !memory_instance.nil?
       end
 
+      # Execute memory action
+      # @param action [String] Action to perform (store, recall, search, recent, stats)
+      # @param category [String, nil] Category for storing memories
+      # @param key [String, nil] Memory key or topic
+      # @param value [String, nil] Memory content to store
+      # @param query [String, nil] Search query for recall/search
+      # @return [String] Action result or error message
       def execute(action:, category: nil, key: nil, value: nil, query: nil, **)
         return error("Memory not initialized") unless memory_instance
 
@@ -82,10 +99,17 @@ module Pocketrb
 
       private
 
+      # Access the memory system from context
+      # @return [Object, nil]
       def memory_instance
         @context[:memory]
       end
 
+      # Store a fact in the specified category
+      # @param category [String] memory category (learned, user, preference, context)
+      # @param key [String] memory key or topic
+      # @param value [String] content to store
+      # @return [String] confirmation or error message
       def store_memory(category, key, value)
         return error("Category, key, and value required") unless category && key && value
 
@@ -105,6 +129,9 @@ module Pocketrb
         success(result)
       end
 
+      # Recall relevant memories matching a query
+      # @param query [String] search query
+      # @return [String] matching memories or not-found message
       def recall_memory(query)
         return error("Query required") unless query
 
@@ -117,6 +144,9 @@ module Pocketrb
         end
       end
 
+      # Deep search across all memory categories
+      # @param query [String] search query
+      # @return [String] search results or not-found message
       def search_memory(query)
         return error("Query required") unless query
 
@@ -134,6 +164,8 @@ module Pocketrb
         lines.join("\n")
       end
 
+      # Show recent events from memory
+      # @return [String] formatted list of recent events
       def show_recent
         events = memory_instance.recent_events(10)
 
@@ -148,6 +180,8 @@ module Pocketrb
         lines.join("\n")
       end
 
+      # Show memory system statistics
+      # @return [String] formatted memory statistics
       def show_stats
         stats = memory_instance.stats
 

data/lib/pocketrb/tools/message.rb

@@ -4,14 +4,20 @@ module Pocketrb
   module Tools
     # Tool for sending messages to chat channels programmatically
     class Message < Base
+      # Tool name
+      # @return [String]
       def name
         "message"
       end
 
+      # Tool description
+      # @return [String]
       def description
         "Send a message to a chat channel. Use this to proactively communicate with users, send notifications, or respond on specific channels."
       end
 
+      # Parameter schema
+      # @return [Hash]
       def parameters
         {
           type: "object",
@@ -33,6 +39,11 @@ module Pocketrb
         }
       end
 
+      # Execute message sending
+      # @param content [String] Message text to send
+      # @param channel [String, nil] Target channel name
+      # @param chat_id [String, nil] Target chat identifier
+      # @return [String] Success or error message
       def execute(content:, channel: nil, chat_id: nil)
         # Use defaults from context if not provided
         channel = (channel || @context[:default_channel])&.to_sym
@@ -56,12 +67,16 @@ module Pocketrb
         success("Message sent to #{channel}:#{chat_id}")
       end
 
+      # Check if message bus is available
+      # @return [Boolean] True if bus is configured
       def available?
         !bus.nil?
       end
 
       private
 
+      # Access the message bus from context
+      # @return [Object, nil]
       def bus
         @context[:bus]
       end

data/lib/pocketrb/tools/para_memory.rb

@@ -4,10 +4,14 @@ module Pocketrb
   module Tools
     # PARA-based memory tool for structured knowledge management
     class ParaMemory < Base
+      # Tool name
+      # @return [String]
       def name
         "para_memory"
       end
 
+      # Tool description
+      # @return [String]
       def description
         <<~DESC.strip
           Structured memory using PARA method. Store and retrieve facts about people, projects,
@@ -16,6 +20,8 @@ module Pocketrb
         DESC
       end
 
+      # Parameter schema
+      # @return [Hash]
       def parameters
         {
           type: "object",
@@ -74,10 +80,25 @@ module Pocketrb
         }
       end
 
+      # Check if tool is available
+      # @return [Boolean] true if PARA manager is configured
       def available?
         !para_manager.nil?
       end
 
+      # Execute memory action
+      # @param action [String] Action to perform (store, search, entity_info, create_entity, list_entities, context,
+      #   preferences, learn_preference)
+      # @option args [String] :content Fact content to store
+      # @option args [String] :category Fact category (relationship, milestone, status, preference, context)
+      # @option args [String] :entity_type PARA entity type (projects, areas, resources, archives)
+      # @option args [String] :entity_name Entity name
+      # @option args [String] :query Search query
+      # @option args [String] :entity_subtype Entity subtype for creation (project, person, company, topic)
+      # @option args [String] :preference_category Preference category
+      # @option args [String] :preference_key Preference key
+      # @option args [String] :preference_value Preference value
+      # @return [String] Action result or error message
       def execute(action:, **args)
         return error("PARA memory not available. Configure memory_dir in agent settings.") unless para_manager
 
@@ -105,10 +126,15 @@ module Pocketrb
 
       private
 
+      # Access the PARA manager from context
+      # @return [Object, nil]
       def para_manager
         @context[:para_manager]
       end
 
+      # Store a fact in the knowledge graph
+      # @param args [Hash] options including :content, :category, :entity_type, :entity_name
+      # @return [String] confirmation or error message
       def store_fact(args)
         content = args[:content]
         return error("Content required") if content.nil? || content.empty?
@@ -131,6 +157,9 @@ module Pocketrb
         end
       end
 
+      # Search across knowledge graph, daily notes, and preferences
+      # @param query [String] search query
+      # @return [String] formatted search results
       def search_memory(query)
         return error("Query required") if query.nil? || query.empty?
 
@@ -166,6 +195,10 @@ module Pocketrb
         lines.join("\n")
       end
 
+      # Get summary information for an entity
+      # @param entity_type [String] PARA type (projects, areas, resources, archives)
+      # @param entity_name [String] entity name
+      # @return [String] entity summary or error message
       def get_entity_info(entity_type, entity_name)
         return error("Entity type and name required") unless entity_type && entity_name
 
@@ -175,6 +208,9 @@ module Pocketrb
         summary
       end
 
+      # Create a new entity in the knowledge graph
+      # @param args [Hash] options including :entity_subtype, :entity_name, :content
+      # @return [String] confirmation or error message
       def create_entity(args)
         subtype = args[:entity_subtype]
         name = args[:entity_name]
@@ -204,6 +240,9 @@ module Pocketrb
         end
       end
 
+      # List entities, optionally filtered by type
+      # @param entity_type [String, nil] PARA type to filter by, or nil for all
+      # @return [String] formatted entity list
       def list_entities(entity_type)
         if entity_type
           entities = para_manager.knowledge_graph.list_entities(entity_type.to_sym)
@@ -220,6 +259,9 @@ module Pocketrb
         end
       end
 
+      # Get relevant context for a query or full summary
+      # @param query [String, nil] context query, or nil for full summary
+      # @return [String] relevant context
       def get_context(query)
         if query && !query.empty?
           para_manager.relevant_context(query)
@@ -228,6 +270,8 @@ module Pocketrb
         end
       end
 
+      # Get all learned user preferences
+      # @return [String] formatted preference list
       def get_preferences
         prefs = para_manager.get_preferences
         return "No learned preferences yet." if prefs.empty?
@@ -243,6 +287,9 @@ module Pocketrb
         lines.join("\n")
       end
 
+      # Store a learned user preference
+      # @param args [Hash] options including :preference_category, :preference_key, :preference_value
+      # @return [String] confirmation or error message
       def learn_preference(args)
         category = args[:preference_category]
         key = args[:preference_key]

data/lib/pocketrb/tools/read_file.rb

@@ -4,14 +4,20 @@ module Pocketrb
   module Tools
     # Read file contents
     class ReadFile < Base
+      # Tool name
+      # @return [String]
       def name
         "read_file"
       end
 
+      # Tool description
+      # @return [String]
       def description
         "Read the contents of a file. Returns the file content as text."
       end
 
+      # Parameter schema
+      # @return [Hash]
       def parameters
         {
           type: "object",
@@ -33,6 +39,11 @@ module Pocketrb
         }
       end
 
+      # Execute file read operation
+      # @param path [String] File path (relative or absolute)
+      # @param offset [Integer, nil] Starting line number (1-indexed)
+      # @param limit [Integer, nil] Maximum lines to read
+      # @return [String] File content or error message
       def execute(path:, offset: nil, limit: nil)
         resolved = validate_path!(path)
 

data/lib/pocketrb/tools/registry.rb

@@ -6,6 +6,8 @@ module Pocketrb
     class Registry
       attr_reader :context
 
+      # Initialize tools registry
+      # @param context [Hash] Context to pass to tool instances (defaults to empty hash)
       def initialize(context = {})
         @tools = {}
         @context = context
@@ -35,7 +37,7 @@ module Pocketrb
 
       # Get a tool by name
       # @param name [String] Tool name
-      # @return [Base|nil]
+      # @return [Base, nil]
       def get(name)
         @tools[name]
       end
@@ -62,7 +64,8 @@ module Pocketrb
       end
 
       # Get Anthropic-format definitions
-      # @return [Array<Hash>]
+      # @param filter_unavailable [Boolean] Exclude unavailable tools (defaults to true)
+      # @return [Array<Hash>] Tool definitions in Anthropic format
       def anthropic_definitions(filter_unavailable: true)
         tools = filter_unavailable ? available_tools : @tools.values
         tools.map(&:to_anthropic_definition)
@@ -113,6 +116,8 @@ module Pocketrb
       end
 
       # Update context for all tools
+      # @param new_context [Hash] New context values to merge
+      # @return [void]
       def update_context(new_context)
         @context = @context.merge(new_context)
         @tools.each_value { |tool| tool.instance_variable_set(:@context, @context) }
@@ -140,8 +145,11 @@ module Pocketrb
 
       private
 
-      # Filter arguments to only include those defined in tool's parameter schema
-      # This prevents LLM from passing unexpected arguments like 'description'
+      # Filter arguments to only include those defined in tool's parameter schema.
+      # This prevents LLM from passing unexpected arguments like 'description'.
+      # @param tool [Base] tool instance with parameter schema
+      # @param args [Hash] raw arguments from LLM
+      # @return [Hash] filtered arguments matching the schema
       def filter_arguments(tool, args)
         schema = tool.parameters
         return args unless schema.is_a?(Hash) && schema[:properties]