prompt_objects 0.1.0

data/lib/prompt_objects/universal/add_capability.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Universal
+    # Universal capability to add capabilities to a prompt object at runtime.
+    # This allows dynamic extension of POs after primitives are created.
+    class AddCapability < Primitive
+      def name
+        "add_capability"
+      end
+
+      def description
+        "Add a capability to a prompt object, allowing it to use new tools. Can target self or another PO."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            target: {
+              type: "string",
+              description: "Name of the prompt object to add the capability to. Use 'self' for the current PO."
+            },
+            capability: {
+              type: "string",
+              description: "Name of the capability to add (must already exist in the registry)"
+            }
+          },
+          required: ["target", "capability"]
+        }
+      end
+
+      def receive(message, context:)
+        target = message[:target] || message["target"]
+        capability = message[:capability] || message["capability"]
+
+        # Resolve 'self' to the calling PO (not current_capability which is this tool)
+        target = context.calling_po if target == "self"
+
+        # Find the target PO
+        target_po = context.env.registry.get(target)
+        unless target_po
+          return "Error: Prompt object '#{target}' not found"
+        end
+
+        unless target_po.is_a?(PromptObject)
+          return "Error: '#{target}' is not a prompt object (can only add capabilities to POs)"
+        end
+
+        # Check if capability exists
+        unless context.env.registry.exists?(capability)
+          return "Error: Capability '#{capability}' does not exist"
+        end
+
+        # Check if already has it
+        current_caps = target_po.config["capabilities"] || []
+        if current_caps.include?(capability)
+          return "'#{target}' already has the '#{capability}' capability"
+        end
+
+        # Add the capability
+        target_po.config["capabilities"] ||= []
+        target_po.config["capabilities"] << capability
+
+        # Persist to file so it's available on restart
+        if target_po.save
+          "Added '#{capability}' to '#{target}' and saved to file. It can now use this capability."
+        else
+          "Added '#{capability}' to '#{target}' (in-memory only, could not save to file). It can now use this capability."
+        end
+      end
+    end
+  end
+end

data/lib/prompt_objects/universal/add_primitive.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Universal
+    # Universal capability to add primitives to the current PO.
+    # Focused version of add_capability specifically for primitives with better UX.
+    class AddPrimitive < Primitive
+      # Names of stdlib primitives (built into the framework)
+      STDLIB_PRIMITIVES = %w[read_file list_files write_file http_get].freeze
+
+      def name
+        "add_primitive"
+      end
+
+      def description
+        "Add a primitive (deterministic Ruby tool) to your capabilities. Use list_primitives first to see what's available."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            primitive: {
+              type: "string",
+              description: "Name of the primitive to add (e.g., 'read_file', 'write_file')"
+            }
+          },
+          required: ["primitive"]
+        }
+      end
+
+      def receive(message, context:)
+        primitive_name = message[:primitive] || message["primitive"]
+
+        # Find the calling PO
+        caller = context.calling_po
+        unless caller
+          return "Error: No calling PO context. This capability adds primitives to the current PO."
+        end
+
+        target_po = context.env.registry.get(caller)
+        unless target_po.is_a?(PromptObject)
+          return "Error: Could not find calling PO '#{caller}'."
+        end
+
+        # Check if primitive exists
+        primitive = context.env.registry.get(primitive_name)
+        unless primitive
+          return suggest_primitives(primitive_name, context)
+        end
+
+        unless primitive.is_a?(Primitive)
+          return "Error: '#{primitive_name}' is not a primitive (it's a prompt object). Use add_capability for POs."
+        end
+
+        # Check if it's a universal capability (shouldn't be added explicitly)
+        if universal_primitive?(primitive)
+          return "Error: '#{primitive_name}' is a universal capability and is already available to all POs."
+        end
+
+        # Check if already has it
+        current_caps = target_po.config["capabilities"] || []
+        if current_caps.include?(primitive_name)
+          return "You already have the '#{primitive_name}' primitive."
+        end
+
+        # Add the primitive
+        target_po.config["capabilities"] ||= []
+        target_po.config["capabilities"] << primitive_name
+
+        # Persist to file so it's available on restart
+        if target_po.save
+          "Added '#{primitive_name}' to your capabilities and saved to file. You can now use it."
+        else
+          "Added '#{primitive_name}' to your capabilities (in-memory only). You can now use it."
+        end
+      end
+
+      private
+
+      def suggest_primitives(name, context)
+        # Get all available primitives (excluding universal ones)
+        available = context.env.registry.primitives
+          .reject { |p| universal_primitive?(p) }
+          .map(&:name)
+
+        # Find similar names
+        suggestions = available.select { |n| n.include?(name) || name.include?(n) || levenshtein_similar?(n, name) }
+
+        if suggestions.any?
+          "Error: Primitive '#{name}' not found. Did you mean: #{suggestions.join(', ')}?"
+        else
+          "Error: Primitive '#{name}' not found. Available primitives: #{available.join(', ')}"
+        end
+      end
+
+      def universal_primitive?(primitive)
+        primitive.class.name&.start_with?("PromptObjects::Universal")
+      end
+
+      # Simple check for similar strings (within 2 edits)
+      def levenshtein_similar?(a, b)
+        return true if a == b
+        return false if (a.length - b.length).abs > 2
+
+        # Simple approximation: check if they share most characters
+        common = (a.chars & b.chars).length
+        max_len = [a.length, b.length].max
+        common.to_f / max_len > 0.6
+      end
+    end
+  end
+end

data/lib/prompt_objects/universal/ask_human.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Universal
+    # Universal capability to pause and ask the human a question.
+    # For now this is synchronous (blocking). In Phase 5 with the TUI,
+    # this will become async with a notification queue.
+    class AskHuman < Primitive
+      def name
+        "ask_human"
+      end
+
+      def description
+        "Pause and ask the human a question. Use this when you need confirmation, clarification, or input."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            question: {
+              type: "string",
+              description: "The question to ask the human"
+            },
+            options: {
+              type: "array",
+              items: { type: "string" },
+              description: "Optional list of choices to present"
+            }
+          },
+          required: ["question"]
+        }
+      end
+
+      def receive(message, context:)
+        question = message[:question] || message["question"]
+        options = message[:options] || message["options"]
+
+        # In TUI mode, use the human queue (non-blocking for UI)
+        if context.tui_mode && context.human_queue
+          return receive_tui(question, options, context)
+        end
+
+        # REPL mode - use stdin directly
+        receive_repl(question, options, context)
+      end
+
+      private
+
+      def receive_tui(question, options, context)
+        # Queue the request and wait for response
+        request = context.human_queue.enqueue(
+          capability: context.current_capability,
+          question: question,
+          options: options
+        )
+
+        # Log to message bus
+        context.bus.publish(
+          from: context.current_capability,
+          to: "human",
+          message: "[waiting] #{question}"
+        )
+
+        # Block this thread until human responds via UI
+        response = request.wait_for_response
+
+        # Log the response
+        context.bus.publish(
+          from: "human",
+          to: context.current_capability,
+          message: response
+        )
+
+        response
+      end
+
+      def receive_repl(question, options, context)
+        puts
+        puts "┌─ #{context.current_capability} asks ──────────────────────────────────┐"
+        puts "│"
+        puts "│  #{question}"
+        puts "│"
+
+        if options && !options.empty?
+          options.each_with_index do |opt, i|
+            puts "│  [#{i + 1}] #{opt}"
+          end
+          puts "│"
+          puts "└──────────────────────────────────────────────────────────────┘"
+          print "Your choice (1-#{options.length}): "
+
+          choice = $stdin.gets&.chomp
+          index = choice.to_i - 1
+
+          if index >= 0 && index < options.length
+            options[index]
+          else
+            choice  # Return raw input if not a valid index
+          end
+        else
+          puts "└──────────────────────────────────────────────────────────────┘"
+          print "Your answer: "
+          $stdin.gets&.chomp || ""
+        end
+      end
+    end
+  end
+end

data/lib/prompt_objects/universal/create_capability.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module PromptObjects
+  module Universal
+    # Universal capability to create new capabilities at runtime.
+    # Can create both prompt objects (markdown) and primitives (Ruby code).
+    # This enables self-modification - the system can create new specialists and tools.
+    class CreateCapability < Primitive
+      def name
+        "create_capability"
+      end
+
+      def description
+        "Create a new capability. Use type='prompt_object' for LLM-backed specialists, or type='primitive' for deterministic Ruby tools."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            type: {
+              type: "string",
+              enum: ["prompt_object", "primitive"],
+              description: "Type of capability: 'prompt_object' for LLM specialists, 'primitive' for Ruby tools"
+            },
+            name: {
+              type: "string",
+              description: "Name for the capability (lowercase, underscores allowed)"
+            },
+            description: {
+              type: "string",
+              description: "Brief description of what this capability does"
+            },
+            # For prompt_objects:
+            capabilities: {
+              type: "array",
+              items: { type: "string" },
+              description: "(prompt_object only) List of capabilities this PO can use"
+            },
+            identity: {
+              type: "string",
+              description: "(prompt_object only) Who is this prompt object? Their personality and role."
+            },
+            behavior: {
+              type: "string",
+              description: "(prompt_object only) How should this prompt object behave?"
+            },
+            # For primitives:
+            parameters_schema: {
+              type: "object",
+              description: "(primitive only) JSON Schema for the parameters this primitive accepts"
+            },
+            ruby_code: {
+              type: "string",
+              description: "(primitive only) Ruby code for the receive method body. Has access to 'message' (Hash) and 'context'."
+            }
+          },
+          required: ["type", "name", "description"]
+        }
+      end
+
+      def receive(message, context:)
+        type = message[:type] || message["type"]
+        cap_name = message[:name] || message["name"]
+
+        # Validate name
+        unless cap_name && cap_name.match?(/\A[a-z][a-z0-9_]*\z/)
+          return "Error: Name must be lowercase letters, numbers, and underscores, starting with a letter."
+        end
+
+        # Check if already exists
+        if context.env.registry.exists?(cap_name)
+          return "Error: A capability named '#{cap_name}' already exists."
+        end
+
+        result = case type
+        when "prompt_object"
+          create_prompt_object(message, context)
+        when "primitive"
+          create_primitive(message, context)
+        else
+          return "Error: type must be 'prompt_object' or 'primitive'"
+        end
+
+        # If creation succeeded, add the new capability to the creating PO
+        if result && !result.start_with?("Error:")
+          added_msg = add_to_creator(cap_name, context)
+          result = "#{result} #{added_msg}" if added_msg
+        end
+
+        result
+      end
+
+      private
+
+      # Add the newly created capability to the PO that created it
+      # Returns a message if added, nil otherwise
+      def add_to_creator(cap_name, context)
+        creator_name = context.calling_po
+        return nil unless creator_name
+
+        creator_po = context.env.registry.get(creator_name)
+        return nil unless creator_po.is_a?(PromptObject)
+
+        # Add to the creator's capabilities if not already present
+        creator_po.config["capabilities"] ||= []
+        unless creator_po.config["capabilities"].include?(cap_name)
+          creator_po.config["capabilities"] << cap_name
+          # Persist the change to file
+          saved = creator_po.save ? " and saved" : ""
+          return "Also added '#{cap_name}' to #{creator_name}'s capabilities#{saved}."
+        end
+
+        nil
+      end
+
+      def create_prompt_object(message, context)
+        cap_name = message[:name] || message["name"]
+        description = message[:description] || message["description"]
+        capabilities = message[:capabilities] || message["capabilities"] || []
+        identity = message[:identity] || message["identity"] || "You are a helpful assistant."
+        behavior = message[:behavior] || message["behavior"] || "Help the user with their request."
+
+        # Build the markdown content
+        frontmatter = {
+          "name" => cap_name,
+          "description" => description,
+          "capabilities" => capabilities
+        }
+
+        body = <<~MARKDOWN
+          # #{cap_name.split('_').map(&:capitalize).join(' ')}
+
+          ## Identity
+
+          #{identity}
+
+          ## Behavior
+
+          #{behavior}
+        MARKDOWN
+
+        # to_yaml already includes leading "---\n", so we just need the closing ---
+        content = "#{frontmatter.to_yaml}---\n\n#{body}"
+
+        # Write to file
+        path = File.join(context.env.objects_dir, "#{cap_name}.md")
+        File.write(path, content, encoding: "UTF-8")
+
+        # Load into environment
+        context.env.load_prompt_object(path)
+
+        "Created prompt object '#{cap_name}' with capabilities: #{capabilities.join(', ')}. It's now available."
+      end
+
+      def create_primitive(message, context)
+        cap_name = message[:name] || message["name"]
+        description = message[:description] || message["description"]
+        params_schema = message[:parameters_schema] || message["parameters_schema"] || {}
+        ruby_code = message[:ruby_code] || message["ruby_code"]
+
+        unless ruby_code
+          return "Error: ruby_code is required for primitives"
+        end
+
+        # Generate the Ruby class
+        class_name = cap_name.split('_').map(&:capitalize).join
+
+        ruby_content = <<~RUBY
+          # frozen_string_literal: true
+          # Auto-generated primitive: #{cap_name}
+
+          module PromptObjects
+            module Primitives
+              class #{class_name} < Primitive
+                def name
+                  "#{cap_name}"
+                end
+
+                def description
+                  "#{description.gsub('"', '\\"')}"
+                end
+
+                def parameters
+                  #{params_schema.inspect}
+                end
+
+                def receive(message, context:)
+                  #{ruby_code.gsub(/^/, '      ').strip}
+                end
+              end
+            end
+          end
+        RUBY
+
+        # Write to primitives directory (uses env.primitives_dir for sandbox support)
+        FileUtils.mkdir_p(context.env.primitives_dir)
+        path = File.join(context.env.primitives_dir, "#{cap_name}.rb")
+        File.write(path, ruby_content, encoding: "UTF-8")
+
+        # Load and register
+        begin
+          load(path)
+          klass = PromptObjects::Primitives.const_get(class_name)
+          context.env.registry.register(klass.new)
+          "Created primitive '#{cap_name}'. It's now available. File: #{path}"
+        rescue SyntaxError => e
+          File.delete(path) if File.exist?(path)
+          "Error: Invalid Ruby syntax - #{e.message}"
+        rescue StandardError => e
+          File.delete(path) if File.exist?(path)
+          "Error creating primitive: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/prompt_objects/universal/create_primitive.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module PromptObjects
+  module Universal
+    # Universal capability to create new primitives (deterministic Ruby code).
+    # This enables POs to create their own tools at runtime.
+    class CreatePrimitive < Primitive
+      def name
+        "create_primitive"
+      end
+
+      def description
+        "Create a new primitive (deterministic Ruby tool). The primitive will be saved to the environment and added to your capabilities."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: "Name for the primitive (lowercase, underscores allowed, e.g., 'parse_json')"
+            },
+            description: {
+              type: "string",
+              description: "Brief description of what this primitive does"
+            },
+            code: {
+              type: "string",
+              description: "Ruby code for the primitive's receive method. Has access to 'message' (Hash with parameters) and 'context'. Should return a String result."
+            },
+            parameters_schema: {
+              type: "object",
+              description: "Optional JSON Schema for the parameters this primitive accepts"
+            }
+          },
+          required: ["name", "description", "code"]
+        }
+      end
+
+      def receive(message, context:)
+        prim_name = message[:name] || message["name"]
+        description = message[:description] || message["description"]
+        code = message[:code] || message["code"]
+        params_schema = message[:parameters_schema] || message["parameters_schema"] || default_params_schema
+
+        # Validate name
+        unless prim_name && prim_name.match?(/\A[a-z][a-z0-9_]*\z/)
+          return "Error: Name must be lowercase letters, numbers, and underscores, starting with a letter."
+        end
+
+        # Check if already exists
+        if context.env.registry.exists?(prim_name)
+          return "Error: A capability named '#{prim_name}' already exists. Use modify_primitive to update it."
+        end
+
+        # Validate code syntax
+        syntax_error = validate_syntax(code)
+        return "Error: Invalid Ruby syntax - #{syntax_error}" if syntax_error
+
+        # Generate the Ruby class
+        class_name = prim_name.split("_").map(&:capitalize).join
+        ruby_content = generate_ruby_class(class_name, prim_name, description, params_schema, code)
+
+        # Write to primitives directory
+        FileUtils.mkdir_p(context.env.primitives_dir)
+        path = File.join(context.env.primitives_dir, "#{prim_name}.rb")
+        File.write(path, ruby_content, encoding: "UTF-8")
+
+        # Load and register
+        begin
+          load(path)
+          klass = PromptObjects::Primitives.const_get(class_name)
+          context.env.registry.register(klass.new)
+        rescue SyntaxError => e
+          File.delete(path) if File.exist?(path)
+          return "Error: Invalid Ruby syntax in generated code - #{e.message}"
+        rescue StandardError => e
+          File.delete(path) if File.exist?(path)
+          return "Error creating primitive: #{e.message}"
+        end
+
+        # Auto-add to the creating PO
+        added_msg = add_to_caller(prim_name, context)
+
+        result = "Created primitive '#{prim_name}' at #{path}."
+        result += " #{added_msg}" if added_msg
+        result
+      end
+
+      private
+
+      def default_params_schema
+        {
+          type: "object",
+          properties: {},
+          required: []
+        }
+      end
+
+      def validate_syntax(code)
+        # Try to parse the code to check for syntax errors
+        eval("proc { #{code} }")
+        nil
+      rescue SyntaxError => e
+        e.message.sub(/^\(eval\):\d+: /, "")
+      rescue StandardError
+        nil # Other errors are OK at this stage
+      end
+
+      def generate_ruby_class(class_name, prim_name, description, params_schema, code)
+        # Escape description for string literal
+        escaped_desc = description.gsub('\\', '\\\\\\\\').gsub('"', '\\"')
+
+        <<~RUBY
+          # frozen_string_literal: true
+          # Auto-generated primitive: #{prim_name}
+          # Created by PO at #{Time.now.iso8601}
+
+          module PromptObjects
+            module Primitives
+              class #{class_name} < Primitive
+                def name
+                  "#{prim_name}"
+                end
+
+                def description
+                  "#{escaped_desc}"
+                end
+
+                def parameters
+                  #{params_schema.inspect}
+                end
+
+                def receive(message, context:)
+                  #{indent_code(code, 10)}
+                end
+              end
+            end
+          end
+        RUBY
+      end
+
+      def indent_code(code, spaces)
+        code.lines.map.with_index do |line, i|
+          i.zero? ? line.rstrip : (" " * spaces) + line.rstrip
+        end.join("\n")
+      end
+
+      def add_to_caller(prim_name, context)
+        caller_name = context.calling_po
+        return nil unless caller_name
+
+        caller_po = context.env.registry.get(caller_name)
+        return nil unless caller_po.is_a?(PromptObject)
+
+        caller_po.config["capabilities"] ||= []
+        unless caller_po.config["capabilities"].include?(prim_name)
+          caller_po.config["capabilities"] << prim_name
+          saved = caller_po.save ? " and saved to file" : ""
+          return "Added '#{prim_name}' to your capabilities#{saved}."
+        end
+
+        nil
+      end
+    end
+  end
+end