pocketrb 0.1.0 → 0.3.0

data/lib/pocketrb/session/session.rb

@@ -7,6 +7,10 @@ module Pocketrb
       attr_reader :key, :metadata, :created_at
       attr_accessor :messages
 
+      # Initialize a new session
+      # @param key [String] Unique session identifier
+      # @param messages [Array<Message>] Initial messages (defaults to empty array)
+      # @param metadata [Hash] Session metadata (defaults to empty hash)
       def initialize(key:, messages: [], metadata: {})
         @key = key
         @messages = messages
@@ -16,15 +20,20 @@ module Pocketrb
       end
 
       # Add a message to the session
-      # @param role [String] Message role
-      # @param content [String] Message content
-      # @param kwargs [Hash] Additional message attributes
-      def add_message(role:, content:, **kwargs)
+      # @param role [String] Message role (user, assistant, tool, system)
+      # @param content [String, Array] Message content (text or content blocks)
+      # @param name [String, nil] Message name (for tool messages)
+      # @param tool_call_id [String, nil] Tool call identifier (for tool result messages)
+      # @param tool_calls [Array<ToolCall>, nil] Tool calls made by assistant
+      # @return [void]
+      def add_message(role:, content:, name: nil, tool_call_id: nil, tool_calls: nil)
         @mutex.synchronize do
           message = Providers::Message.new(
             role: role,
             content: content,
-            **kwargs
+            name: name,
+            tool_call_id: tool_call_id,
+            tool_calls: tool_calls
           )
           @messages << message
           save_to_log(message)
@@ -61,6 +70,9 @@ module Pocketrb
       end
 
       # Add an assistant message
+      # @param content [String] Assistant response text
+      # @param tool_calls [Array<ToolCall>, nil] Tool calls made by the assistant
+      # @return [void]
       def add_assistant_message(content, tool_calls: nil)
         # Truncate large tool call arguments to prevent context bloat
         sanitized_calls = sanitize_tool_calls(tool_calls) if tool_calls
@@ -70,6 +82,11 @@ module Pocketrb
       # Add a tool result message
       MAX_TOOL_RESULT_LENGTH = 2000
 
+      # Add a tool execution result
+      # @param tool_call_id [String] Tool call identifier to link result to request
+      # @param name [String] Tool name
+      # @param content [String] Tool execution result or output
+      # @return [void]
       def add_tool_result(tool_call_id:, name:, content:)
         # Truncate large tool results to prevent context bloat
         truncated_content = if content.is_a?(String) && content.length > MAX_TOOL_RESULT_LENGTH
@@ -87,7 +104,7 @@ module Pocketrb
       end
 
       # Get message history (optionally limited)
-      # @param max_messages [Integer|nil] Maximum messages to return
+      # @param max_messages [Integer, nil] Maximum messages to return
       # @return [Array<Message>]
       def get_history(max_messages: nil)
         @mutex.synchronize do
@@ -97,39 +114,56 @@ module Pocketrb
         end
       end
 
-      # Clear all messages
+      # Clear all messages from session
+      # @return [void]
       def clear
         @mutex.synchronize do
           @messages.clear
         end
       end
 
-      # Get the last message
+      # Get the last message in the session
+      # @return [Providers::Message, nil] last message or nil
       def last_message
         @mutex.synchronize { @messages.last }
       end
 
-      # Number of messages
+      # Number of messages in session
+      # @return [Integer] message count
       def message_count
         @mutex.synchronize { @messages.size }
       end
 
-      # Check if session is empty
+      # Check if session has no messages
+      # @return [Boolean] true if no messages
       def empty?
         @mutex.synchronize { @messages.empty? }
       end
 
+      # Yield to block while holding the session mutex
+      # @yield Block to execute under the session lock
+      # @return [Object] Return value of the block
+      def with_lock(&)
+        @mutex.synchronize(&)
+      end
+
       # Set metadata value
+      # @param key [String, Symbol] Metadata key
+      # @param value [Object] Metadata value (any serializable object)
+      # @return [void]
       def set_meta(key, value)
         @mutex.synchronize { @metadata[key] = value }
       end
 
       # Get metadata value
+      # @param key [String, Symbol] Metadata key
+      # @return [Object, nil] Stored value or nil
       def get_meta(key)
         @mutex.synchronize { @metadata[key] }
       end
 
-      # Convert to hash for serialization
+      # Convert session to hash for serialization
+      # @return [Hash] serialized session data
       def to_h
         @mutex.synchronize do
           {
@@ -142,6 +176,8 @@ module Pocketrb
       end
 
       # Create from hash
+      # @param hash [Hash] Serialized session data
+      # @return [Session] Reconstructed session instance
       def self.from_h(hash)
         messages = (hash[:messages] || hash["messages"] || []).map do |m|
           Providers::Message.new(
@@ -174,6 +210,9 @@ module Pocketrb
       # Large content (scripts, files) shouldn't be stored in session history
       MAX_ARG_LENGTH = 500
 
+      # Truncate large arguments in tool calls to prevent context bloat
+      # @param tool_calls [Array<Providers::ToolCall>, nil] tool calls to sanitize
+      # @return [Array<Providers::ToolCall>, nil] sanitized tool calls
       def sanitize_tool_calls(tool_calls)
         return nil if tool_calls.nil?
 
@@ -195,6 +234,9 @@ module Pocketrb
         end
       end
 
+      # Hook for real-time logging of messages
+      # @param message [Providers::Message] newly appended conversation turn for real-time logging
+      # @return [void]
       def save_to_log(message)
         # Session manager handles persistence via JSONL
         # This is a hook for real-time logging if needed

data/lib/pocketrb/skills/builtin/tmux/SKILL.md

@@ -40,7 +40,7 @@ SOCKET="$SOCKET_DIR/pocketrb.sock"
 tmux -S "$SOCKET" new-session -d -s mysession
 
 # Create session with initial command
-tmux -S "$SOCKET" new-session -d -s mysession "python3"
+tmux -S "$SOCKET" new-session -d -s mysession "irb"
 
 # List sessions
 tmux -S "$SOCKET" list-sessions
@@ -86,7 +86,7 @@ tmux -S "$SOCKET" capture-pane -p -t mysession > output.txt
 
 ```bash
 # Send command
-tmux -S "$SOCKET" send-keys -t mysession "python3 script.py" Enter
+tmux -S "$SOCKET" send-keys -t mysession "ruby script.rb" Enter
 
 # Wait for completion (simple approach)
 sleep 2
@@ -95,19 +95,19 @@ sleep 2
 tmux -S "$SOCKET" capture-pane -p -J -t mysession -S -50
 ```
 
-### Interactive Python/REPL Session
+### Interactive Ruby/IRB Session
 
 ```bash
-# Start Python session
-tmux -S "$SOCKET" new-session -d -s python "python3"
+# Start IRB session
+tmux -S "$SOCKET" new-session -d -s ruby "irb"
 
-# Send Python commands
-tmux -S "$SOCKET" send-keys -t python "import os" Enter
-tmux -S "$SOCKET" send-keys -t python "print(os.getcwd())" Enter
+# Send Ruby commands
+tmux -S "$SOCKET" send-keys -t ruby "require 'pathname'" Enter
+tmux -S "$SOCKET" send-keys -t ruby "puts Pathname.pwd" Enter
 
 # Get output
 sleep 1
-tmux -S "$SOCKET" capture-pane -p -t python
+tmux -S "$SOCKET" capture-pane -p -t ruby
 ```
 
 ### SSH Session

data/lib/pocketrb/skills/create_tool.rb

@@ -1,17 +1,24 @@
 # frozen_string_literal: true
 
 module Pocketrb
+  # Skills system for reusable prompts and capabilities
   module Skills
     # Tool for creating new skills at runtime
     class CreateTool < Tools::Base
+      # Tool name
+      # @return [String] Tool identifier
       def name
         "skill_create"
       end
 
+      # Tool description
+      # @return [String] Human-readable description
       def description
         "Create a new skill. Skills are reusable prompts/instructions that can be loaded into context. Use this to teach yourself new capabilities."
       end
 
+      # Tool parameters schema
+      # @return [Hash] JSON schema for tool parameters
       def parameters
         {
           type: "object",
@@ -42,6 +49,13 @@ module Pocketrb
         }
       end
 
+      # Execute skill creation
+      # @param skill_name [String] Skill name (lowercase, hyphens allowed)
+      # @param skill_description [String] Brief skill description
+      # @param content [String] Skill content/instructions in markdown
+      # @param triggers [Array<String>, nil] Keywords that trigger this skill
+      # @param always [Boolean] Whether skill should always be loaded (defaults to false)
+      # @return [String] Success or error message
       def execute(skill_name:, skill_description:, content:, triggers: nil, always: false)
         # Validate skill name
         unless valid_skill_name?(skill_name)
@@ -70,10 +84,20 @@ module Pocketrb
 
       private
 
+      # Validate skill name format (lowercase alphanumeric with hyphens)
+      # @param name [String] skill name to validate
+      # @return [Boolean] true if name is valid
       def valid_skill_name?(name)
         name.match?(/\A[a-z][a-z0-9-]*\z/)
       end
 
+      # Build SKILL.md content with YAML frontmatter
+      # @param name [String] skill name
+      # @param description [String] skill description
+      # @param content [String] skill body content
+      # @param triggers [Array<String>, nil] trigger keywords
+      # @param always [Boolean] whether to always load the skill
+      # @return [String] complete SKILL.md file content
       def build_skill_file(name, description, content, triggers, always)
         metadata = {
           "name" => name,
@@ -90,6 +114,10 @@ module Pocketrb
         MD
       end
 
+      # Append skill entry to TOOLS.md if it exists
+      # @param skill_name [String] skill name to add
+      # @param description [String] skill description
+      # @return [void]
       def update_tools_documentation(skill_name, description)
         tools_file = workspace.join("TOOLS.md")
         return unless tools_file.exist?

data/lib/pocketrb/skills/loader.rb

@@ -6,11 +6,16 @@ module Pocketrb
   module Skills
     # Loads and manages skills from SKILL.md files
     class Loader
+      # Filename for skill definition
       SKILL_FILE = "SKILL.md"
+      # Regex to parse YAML frontmatter in skill files
       FRONTMATTER_REGEX = /\A---\s*\n(.+?)\n---\s*\n/m
 
       attr_reader :workspace, :builtin_dir
 
+      # Initialize skills loader
+      # @param workspace [String, Pathname] Workspace directory containing skills/ folder
+      # @param builtin_dir [String, Pathname, nil] Directory with builtin skills (defaults to gem's builtin dir)
       def initialize(workspace:, builtin_dir: nil)
         @workspace = Pathname.new(workspace)
         @builtin_dir = if builtin_dir
@@ -43,7 +48,7 @@ module Pocketrb
 
       # Load a specific skill by name
       # @param name [String] Skill name
-      # @return [Skill|nil]
+      # @return [Skill, nil]
       def load_skill(name)
         @skills_cache[name] ||= find_and_load_skill(name)
       end
@@ -84,12 +89,16 @@ module Pocketrb
       end
 
       # Clear the skills cache
+      # @return [void]
       def clear_cache!
         @skills_cache.clear
       end
 
       private
 
+      # Load all skills from a directory and its subdirectories
+      # @param dir [Pathname] directory to scan for SKILL.md files
+      # @return [Array<Skill>] loaded skills
       def load_from_directory(dir)
         return [] unless dir.exist?
 
@@ -108,6 +117,9 @@ module Pocketrb
         skills.compact
       end
 
+      # Find and load a skill by name from workspace or builtin directories
+      # @param name [String] skill name to find
+      # @return [Skill, nil] loaded skill or nil if not found
       def find_and_load_skill(name)
         # Check workspace skills
         skill_path = @workspace.join("skills", name, SKILL_FILE)
@@ -122,6 +134,9 @@ module Pocketrb
         nil
       end
 
+      # Parse a SKILL.md file into a Skill object
+      # @param path [Pathname] path to SKILL.md file
+      # @return [Skill, nil] parsed skill or nil on error
       def parse_skill_file(path)
         return nil unless path.exist?
 
@@ -143,6 +158,9 @@ module Pocketrb
         nil
       end
 
+      # Extract YAML frontmatter and body from markdown content
+      # @param content [String] raw file content
+      # @return [Array] two-element array of metadata Hash and body String
       def extract_frontmatter(content)
         if content.match?(FRONTMATTER_REGEX)
           match = content.match(FRONTMATTER_REGEX)
@@ -154,6 +172,9 @@ module Pocketrb
         end
       end
 
+      # Extract a description from the first line of markdown body
+      # @param body [String] markdown body text
+      # @return [String] extracted description
       def extract_description(body)
         # Extract first line or paragraph as description
         first_line = body.lines.first&.strip

data/lib/pocketrb/skills/modify_tool.rb

@@ -4,14 +4,20 @@ module Pocketrb
   module Skills
     # Tool for modifying existing skills
     class ModifyTool < Tools::Base
+      # Tool name
+      # @return [String] Tool identifier
       def name
         "skill_modify"
       end
 
+      # Tool description
+      # @return [String] Human-readable description
       def description
         "Modify an existing skill. Can update the content, description, triggers, or other properties."
       end
 
+      # Tool parameters schema
+      # @return [Hash] JSON schema for tool parameters
       def parameters
         {
           type: "object",
@@ -51,6 +57,15 @@ module Pocketrb
         }
       end
 
+      # Execute skill modification
+      # @param skill_name [String] Name of skill to modify
+      # @param new_content [String, nil] Replace entire skill content
+      # @param append_content [String, nil] Append to existing content
+      # @param new_description [String, nil] Update skill description
+      # @param add_triggers [Array<String>, nil] Add trigger keywords
+      # @param remove_triggers [Array<String>, nil] Remove trigger keywords
+      # @param set_always [Boolean, nil] Set always-load flag
+      # @return [String] Success or error message
       def execute(
         skill_name:,
         new_content: nil,
@@ -99,6 +114,9 @@ module Pocketrb
 
       private
 
+      # Parse YAML frontmatter from skill file content
+      # @param content [String] raw file content with optional frontmatter
+      # @return [Array] two-element array of metadata Hash and body String
       def parse_frontmatter(content)
         if content.match?(/\A---\s*\n(.+?)\n---\s*\n/m)
           match = content.match(/\A---\s*\n(.+?)\n---\s*\n/m)
@@ -110,6 +128,10 @@ module Pocketrb
         end
       end
 
+      # Build SKILL.md content from metadata and body
+      # @param metadata [Hash] YAML frontmatter data
+      # @param body [String] markdown body content
+      # @return [String] complete SKILL.md file content
       def build_skill_file(metadata, body)
         <<~MD
           ---

data/lib/pocketrb/skills/skill.rb

@@ -6,6 +6,12 @@ module Pocketrb
     class Skill
       attr_reader :name, :description, :content, :path, :metadata
 
+      # Initialize skill
+      # @param name [String] Skill name
+      # @param description [String] Skill description
+      # @param content [String] Skill markdown content
+      # @param path [Pathname] Path to skill file
+      # @param metadata [Hash] Skill metadata (triggers, always, requires, etc.) (defaults to empty hash)
       def initialize(name:, description:, content:, path:, metadata: {})
         @name = name
         @description = description
@@ -15,11 +21,13 @@ module Pocketrb
       end
 
       # Check if skill should always be included in context
+      # @return [Boolean] true if always-load flag is set
       def always?
         metadata[:always] == true || metadata["always"] == true
       end
 
-      # Check if skill is available (meets requirements)
+      # Check if skill is available (all requirements met)
+      # @return [Boolean] true if all requirements are satisfied
       def available?
         requires = metadata[:requires] || metadata["requires"]
         return true unless requires
@@ -27,13 +35,16 @@ module Pocketrb
         Array(requires).all? { |req| check_requirement(req) }
       end
 
-      # Get skill triggers/keywords
+      # Get skill trigger keywords
+      # @return [Array<String>] trigger keywords
       def triggers
         triggers = metadata[:triggers] || metadata["triggers"] || []
         Array(triggers)
       end
 
       # Check if a message should trigger this skill
+      # @param text [String] Message text to check against triggers
+      # @return [Boolean] True if any trigger matches
       def matches?(text)
         return false if triggers.empty?
 
@@ -42,6 +53,7 @@ module Pocketrb
       end
 
       # Get full prompt content for this skill
+      # @return [String] XML-wrapped skill prompt
       def to_prompt
         <<~PROMPT
           <skill name="#{name}">
@@ -50,13 +62,17 @@ module Pocketrb
         PROMPT
       end
 
-      # Summary for skills list
+      # Summary line for skills list
+      # @return [String] formatted summary
       def to_summary
         "- #{name}: #{description}"
       end
 
       private
 
+      # Check if a single requirement is satisfied
+      # @param req [String] requirement string (e.g., "env:VAR", "file:path", "tool:name")
+      # @return [Boolean] true if requirement is met
       def check_requirement(req)
         case req
         when /^env:(.+)/

data/lib/pocketrb/tools/background_job_manager.rb

@@ -6,7 +6,9 @@ module Pocketrb
   module Tools
     # Manages background jobs for long-running commands
     class BackgroundJobManager
+      # Maximum number of concurrent background jobs
       MAX_JOBS = 50
+      # Maximum number of completed job records to retain
       MAX_COMPLETED_JOBS = 20
       MAX_JOB_AGE = 24 * 60 * 60 # 24 hours
 
@@ -32,6 +34,8 @@ module Pocketrb
 
       attr_reader :jobs_dir
 
+      # Initialize background job manager
+      # @param workspace [String, Pathname] Workspace directory path for storing job state
       def initialize(workspace:)
         @workspace = Pathname.new(workspace)
         @jobs_dir = resolve_jobs_dir
@@ -40,12 +44,15 @@ module Pocketrb
       end
 
       # Check if job manager is available (directory accessible)
+      # @return [Boolean] true if the jobs directory is usable
       def available?
         @available
       end
 
       private
 
+      # Determine the directory for storing job state files
+      # @return [Pathname]
       def resolve_jobs_dir
         # Don't create .pocketrb in root filesystem
         if @workspace.to_s == "/" || !@workspace.writable?
@@ -55,6 +62,8 @@ module Pocketrb
         end
       end
 
+      # Create the jobs directory if it does not exist
+      # @return [Boolean] true if directory is accessible
       def setup_jobs_dir!
         FileUtils.mkdir_p(@jobs_dir)
         true
@@ -66,6 +75,8 @@ module Pocketrb
       public
 
       # Check if command should auto-run in background
+      # @param command [String] Shell command to analyze
+      # @return [Boolean] true if command matches long-running patterns
       def long_running?(command)
         return false if command.nil? || command.empty?
 
@@ -73,6 +84,10 @@ module Pocketrb
       end
 
       # Start a background job
+      # @param command [String] Shell command to execute in background
+      # @param working_dir [String, nil] Working directory for command execution
+      # @param name [String, nil] Human-readable job name
+      # @return [Hash] Job metadata including ID and status
       def start(command:, working_dir: nil, name: nil)
         cleanup_stale_jobs
 
@@ -138,6 +153,8 @@ module Pocketrb
       end
 
       # Get job status and output
+      # @param job_id [String] Job identifier
+      # @return [Hash, nil] Job metadata with status, output, and command info
       def status(job_id)
         job_dir = @jobs_dir.join(job_id)
         return nil unless job_dir.exist?
@@ -164,6 +181,9 @@ module Pocketrb
       end
 
       # Get job output (tail)
+      # @param job_id [String] Job identifier
+      # @param lines [Integer] Number of recent output lines to retrieve
+      # @return [String, nil] Recent output lines or nil if job not found
       def output(job_id, lines: 50)
         log_file = @jobs_dir.join(job_id, "output.log")
         return nil unless log_file.exist?
@@ -172,6 +192,8 @@ module Pocketrb
       end
 
       # Kill a job
+      # @param job_id [String] Job identifier
+      # @return [Boolean] true if job was killed successfully
       def kill(job_id)
         pid_file = @jobs_dir.join(job_id, "pid")
         return false unless pid_file.exist?
@@ -244,6 +266,9 @@ module Pocketrb
 
       private
 
+      # Check if a process is still running
+      # @param pid [Integer] process ID to check
+      # @return [Boolean] true if process exists and is running
       def process_running?(pid)
         Process.kill(0, pid)
         true
@@ -251,6 +276,10 @@ module Pocketrb
         false
       end
 
+      # Truncate output that exceeds the maximum size
+      # @param output [String] output text to truncate
+      # @param max_size [Integer] maximum allowed character count
+      # @return [String] truncated or original output
       def truncate_output(output, max_size: 100_000)
         return output if output.length <= max_size
 

data/lib/pocketrb/tools/base.rb

@@ -6,6 +6,8 @@ module Pocketrb
     class Base
       attr_reader :context
 
+      # Initialize tool instance
+      # @param context [Hash] Shared context hash containing workspace, bus, and other runtime dependencies
       def initialize(context = {})
         @context = context
       end
@@ -29,8 +31,9 @@ module Pocketrb
       end
 
       # Execute the tool
-      # @param kwargs [Hash] Tool arguments
+      # @option kwargs [Object] * Tool-specific arguments as defined in the parameters schema
       # @return [String] Result
+      # @note Subclasses should override this method and define specific parameters matching their schema
       def execute(**kwargs)
         raise NotImplementedError, "#{self.class}#execute must be implemented"
       end
@@ -67,11 +70,15 @@ module Pocketrb
       protected
 
       # Helper to build a successful result
+      # @param message [Object] content to convert to string
+      # @return [String]
       def success(message)
         message.to_s
       end
 
       # Helper to build an error result
+      # @param message [String] error description
+      # @return [String]
       def error(message)
         "Error: #{message}"
       end
@@ -87,6 +94,8 @@ module Pocketrb
       end
 
       # Resolve a path relative to workspace
+      # @param path [String] file or directory path
+      # @return [Pathname]
       def resolve_path(path)
         return Pathname.new(path) if Pathname.new(path).absolute?
 
@@ -94,6 +103,8 @@ module Pocketrb
       end
 
       # Check if path is within workspace (security)
+      # @param path [String] file or directory path to check
+      # @return [Boolean]
       def path_allowed?(path)
         return true unless workspace
 
@@ -104,6 +115,10 @@ module Pocketrb
       end
 
       # Validate path is allowed and exists
+      # @param path [String] file or directory path to validate
+      # @param must_exist [Boolean] whether the path must already exist
+      # @return [Pathname] resolved path
+      # @raise [ToolError] if path is outside workspace or does not exist
       def validate_path!(path, must_exist: true)
         resolved = resolve_path(path)