prompt_objects 0.1.0

data/lib/prompt_objects/environment/manifest.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "time"
+
+module PromptObjects
+  module Env
+    # Handles environment manifest files (manifest.yml).
+    # Contains metadata about the environment: name, description, timestamps,
+    # UI customization, and stats.
+    class Manifest
+      FILENAME = "manifest.yml"
+      FORMAT_VERSION = 1  # Increment when manifest schema changes
+
+      attr_accessor :name, :description, :created_at, :updated_at, :last_opened,
+                    :icon, :color, :tags, :default_po, :stats, :version,
+                    :archived_at, :imported_from, :imported_at
+
+      def initialize(
+        name:,
+        description: nil,
+        created_at: nil,
+        updated_at: nil,
+        last_opened: nil,
+        icon: nil,
+        color: nil,
+        tags: nil,
+        default_po: nil,
+        stats: nil,
+        version: nil,
+        archived_at: nil,
+        imported_from: nil,
+        imported_at: nil
+      )
+        @name = name
+        @description = description
+        @created_at = created_at || Time.now
+        @updated_at = updated_at || Time.now
+        @last_opened = last_opened
+        @icon = icon || "📦"
+        @color = color || "#4A90D9"
+        @tags = tags || []
+        @default_po = default_po
+        @stats = stats || { "total_messages" => 0, "total_sessions" => 0, "po_count" => 0 }
+        @version = version || FORMAT_VERSION
+        @archived_at = archived_at
+        @imported_from = imported_from
+        @imported_at = imported_at
+      end
+
+      # Load manifest from a file path.
+      # @param path [String] Path to manifest.yml
+      # @return [Manifest]
+      def self.load(path)
+        raise Error, "Manifest not found: #{path}" unless File.exist?(path)
+
+        data = YAML.safe_load(File.read(path), permitted_classes: [Time, Symbol])
+        from_hash(data)
+      end
+
+      # Load manifest from an environment directory.
+      # @param env_dir [String] Path to environment directory
+      # @return [Manifest]
+      def self.load_from_dir(env_dir)
+        load(File.join(env_dir, FILENAME))
+      end
+
+      # Create manifest from a hash (parsed YAML).
+      # @param data [Hash]
+      # @return [Manifest]
+      def self.from_hash(data)
+        new(
+          name: data["name"],
+          description: data["description"],
+          created_at: parse_time(data["created_at"]),
+          updated_at: parse_time(data["updated_at"]),
+          last_opened: parse_time(data["last_opened"]),
+          icon: data["icon"],
+          color: data["color"],
+          tags: data["tags"],
+          default_po: data["default_po"],
+          stats: data["stats"],
+          version: data["version"],
+          archived_at: parse_time(data["archived_at"]),
+          imported_from: data["imported_from"],
+          imported_at: parse_time(data["imported_at"])
+        )
+      end
+
+      # Parse time from various formats.
+      # @param value [String, Time, nil]
+      # @return [Time, nil]
+      def self.parse_time(value)
+        return nil if value.nil?
+        return value if value.is_a?(Time)
+
+        Time.parse(value)
+      rescue ArgumentError
+        nil
+      end
+
+      # Convert to hash for YAML serialization.
+      # @return [Hash]
+      def to_hash
+        {
+          "version" => @version,
+          "name" => @name,
+          "description" => @description,
+          "created_at" => @created_at&.iso8601,
+          "updated_at" => @updated_at&.iso8601,
+          "last_opened" => @last_opened&.iso8601,
+          "archived_at" => @archived_at&.iso8601,
+          "imported_from" => @imported_from,
+          "imported_at" => @imported_at&.iso8601,
+          "icon" => @icon,
+          "color" => @color,
+          "tags" => @tags.any? ? @tags : nil,
+          "default_po" => @default_po,
+          "stats" => @stats
+        }.compact
+      end
+
+      # Save manifest to a file.
+      # @param path [String] Path to save manifest.yml
+      def save(path)
+        @updated_at = Time.now
+        File.write(path, to_hash.to_yaml)
+      end
+
+      # Save manifest to an environment directory.
+      # @param env_dir [String] Path to environment directory
+      def save_to_dir(env_dir)
+        save(File.join(env_dir, FILENAME))
+      end
+
+      # Mark environment as opened and update timestamp.
+      def touch_opened!
+        @last_opened = Time.now
+        @updated_at = Time.now
+      end
+
+      # Update stats from environment data.
+      # @param po_count [Integer] Number of prompt objects
+      # @param session_count [Integer] Number of sessions
+      # @param message_count [Integer] Total messages
+      def update_stats(po_count: nil, session_count: nil, message_count: nil)
+        @stats["po_count"] = po_count if po_count
+        @stats["total_sessions"] = session_count if session_count
+        @stats["total_messages"] = message_count if message_count
+        @updated_at = Time.now
+      end
+
+      # Increment message count.
+      def increment_messages!
+        @stats["total_messages"] = (@stats["total_messages"] || 0) + 1
+      end
+
+      # Mark as archived with timestamp.
+      def mark_archived!
+        @archived_at = Time.now
+        @updated_at = Time.now
+      end
+
+      # Check if this environment was imported.
+      # @return [Boolean]
+      def imported?
+        !@imported_from.nil?
+      end
+
+      # Check if this environment was archived.
+      # @return [Boolean]
+      def archived?
+        !@archived_at.nil?
+      end
+
+      # Display string.
+      # @return [String]
+      def to_s
+        "#{@icon} #{@name}"
+      end
+
+      # Detailed info string.
+      # @return [String]
+      def info
+        lines = []
+        lines << "#{@icon} #{@name}"
+        lines << "  #{@description}" if @description
+        lines << ""
+        lines << "  Created: #{@created_at&.strftime('%Y-%m-%d %H:%M')}"
+        lines << "  Last opened: #{@last_opened&.strftime('%Y-%m-%d %H:%M')}" if @last_opened
+        lines << "  Updated: #{@updated_at&.strftime('%Y-%m-%d %H:%M')}" if @updated_at
+
+        if imported?
+          lines << ""
+          lines << "  Imported from: #{@imported_from}"
+          lines << "  Imported at: #{@imported_at&.strftime('%Y-%m-%d %H:%M')}"
+        end
+
+        if archived?
+          lines << ""
+          lines << "  Archived at: #{@archived_at&.strftime('%Y-%m-%d %H:%M')}"
+        end
+
+        lines << ""
+        lines << "  Stats:"
+        lines << "    Objects: #{@stats['po_count'] || 0}"
+        lines << "    Sessions: #{@stats['total_sessions'] || 0}"
+        lines << "    Messages: #{@stats['total_messages'] || 0}"
+
+        lines << ""
+        lines << "  Tags: #{@tags.join(', ')}" if @tags&.any?
+        lines << "  Format version: #{@version}"
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/prompt_objects/environment.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  # Context object passed to capabilities during execution.
+  # Provides access to environment, message bus, and tracks execution.
+  class Context
+    attr_reader :env, :bus, :human_queue
+    attr_accessor :current_capability, :calling_po, :tui_mode
+
+    def initialize(env:, bus:, human_queue: nil)
+      @env = env
+      @bus = bus
+      @human_queue = human_queue
+      @current_capability = nil
+      @calling_po = nil  # The PO that initiated the tool call (for resolving "self")
+      @tui_mode = false
+    end
+
+    # Log a message to the bus.
+    # @param to [String] Destination capability
+    # @param message [String, Hash] The message
+    def log_message(to:, message:)
+      @bus.publish(from: @current_capability || "human", to: to, message: message)
+    end
+
+    # Log a response to the bus.
+    # @param from [String] Source capability
+    # @param message [String, Hash] The response
+    def log_response(from:, message:)
+      @bus.publish(from: from, to: @current_capability || "human", message: message)
+    end
+  end
+
+  # The runtime environment that holds all capabilities and coordinates execution.
+  # Can be initialized either from:
+  # - A user environment directory (with manifest.yml, git integration)
+  # - A simple objects directory (legacy/development mode)
+  class Runtime
+    attr_reader :llm, :registry, :objects_dir, :bus, :primitives_dir, :human_queue,
+                :manifest, :env_path, :auto_commit, :session_store,
+                :current_provider, :current_model
+    attr_accessor :on_po_registered  # Callback for when a PO is registered
+
+    # Initialize from an environment path (with manifest) or objects directory.
+    # @param env_path [String, nil] Path to environment directory (preferred)
+    # @param objects_dir [String, nil] Legacy: path to objects directory
+    # @param primitives_dir [String, nil] Path to primitives directory
+    # @param llm [Object, nil] LLM adapter (deprecated, use provider/model instead)
+    # @param provider [String, nil] LLM provider (openai, anthropic, gemini)
+    # @param model [String, nil] Model name
+    # @param auto_commit [Boolean] Auto-commit changes to git (default: true for env_path)
+    def initialize(env_path: nil, objects_dir: nil, primitives_dir: nil, llm: nil, provider: nil, model: nil, auto_commit: nil)
+      if env_path
+        # Environment-based initialization
+        @env_path = env_path
+        @objects_dir = File.join(env_path, "objects")
+        @primitives_dir = primitives_dir || File.join(env_path, "primitives")
+        @manifest = Env::Manifest.load_from_dir(env_path)
+        @auto_commit = auto_commit.nil? ? true : auto_commit
+        @manifest.touch_opened!
+        @manifest.save_to_dir(env_path)
+
+        # Initialize session store
+        db_path = File.join(env_path, "sessions.db")
+        @session_store = Session::Store.new(db_path)
+      else
+        # Legacy objects_dir initialization
+        @env_path = nil
+        @objects_dir = objects_dir || "objects"
+        @primitives_dir = primitives_dir || File.join(File.dirname(@objects_dir), "primitives")
+        @manifest = nil
+        @auto_commit = auto_commit || false
+        @session_store = nil  # No persistent sessions in legacy mode
+      end
+
+      # Initialize LLM - prefer explicit llm, then use factory with provider/model
+      if llm
+        @llm = llm
+        @current_provider = nil
+        @current_model = nil
+      else
+        @current_provider = provider || LLM::Factory::DEFAULT_PROVIDER
+        @current_model = model || LLM::Factory.default_model(@current_provider)
+        @llm = LLM::Factory.create(provider: @current_provider, model: @current_model)
+      end
+
+      @registry = Registry.new
+      @bus = MessageBus.new
+      @human_queue = HumanQueue.new
+
+      register_primitives
+      register_universal_capabilities
+    end
+
+    # Create runtime from a user environment by name.
+    # @param name [String] Environment name
+    # @param manager [Env::Manager, nil] Manager instance
+    # @return [Runtime]
+    def self.from_environment(name, manager: nil)
+      manager ||= Env::Manager.new
+      raise Error, "Environment '#{name}' not found" unless manager.environment_exists?(name)
+
+      new(env_path: manager.environment_path(name))
+    end
+
+    # Name of the environment (from manifest or directory name).
+    # @return [String]
+    def name
+      @manifest&.name || File.basename(@objects_dir)
+    end
+
+    # Check if this is an environment-based runtime (vs legacy objects_dir).
+    # @return [Boolean]
+    def environment?
+      !@env_path.nil?
+    end
+
+    # Save a commit with all current changes.
+    # @param message [String]
+    # @return [Boolean] True if committed
+    def save(message = "Save changes")
+      return false unless environment? && @auto_commit
+
+      Env::Git.auto_commit(@env_path, message)
+    end
+
+    # Check if there are unsaved changes.
+    # @return [Boolean]
+    def dirty?
+      return false unless environment?
+
+      Env::Git.dirty?(@env_path)
+    end
+
+    # Switch to a different LLM provider/model.
+    # @param provider [String] Provider name (openai, anthropic, gemini)
+    # @param model [String, nil] Model name (defaults to provider's default)
+    # @return [Hash] New provider/model info
+    def switch_llm(provider:, model: nil)
+      @current_provider = provider
+      @current_model = model || LLM::Factory.default_model(provider)
+      @llm = LLM::Factory.create(provider: @current_provider, model: @current_model)
+
+      # Update all loaded POs to use the new LLM
+      @registry.prompt_objects.each do |po|
+        po.instance_variable_set(:@llm, @llm)
+      end
+
+      { provider: @current_provider, model: @current_model }
+    end
+
+    # Get current LLM configuration.
+    # @return [Hash]
+    def llm_config
+      {
+        provider: @current_provider,
+        model: @current_model,
+        providers: LLM::Factory.providers,
+        available: LLM::Factory.available_providers
+      }
+    end
+
+    # Update manifest stats from current state.
+    def update_manifest_stats!
+      return unless @manifest
+
+      stats = { po_count: @registry.prompt_objects.size }
+
+      # Add session stats if available
+      if @session_store
+        stats[:total_sessions] = @session_store.total_sessions
+        stats[:total_messages] = @session_store.total_messages
+      end
+
+      @manifest.update_stats(**stats)
+      @manifest.save_to_dir(@env_path)
+    end
+
+    # Create a context for capability execution.
+    # @param tui_mode [Boolean] Whether running in TUI mode
+    # @return [Context]
+    def context(tui_mode: false)
+      ctx = Context.new(env: self, bus: @bus, human_queue: @human_queue)
+      ctx.tui_mode = tui_mode
+      ctx
+    end
+
+    # Load a prompt object from a file path.
+    # @param path [String] Path to the .md file
+    # @return [PromptObject]
+    def load_prompt_object(path)
+      data = Loader.load(path)
+
+      po = PromptObject.new(
+        config: data[:config],
+        body: data[:body],
+        env: self,
+        llm: @llm,
+        path: data[:path]
+      )
+
+      @registry.register(po)
+
+      # Notify callback if registered (for live updates in web UI)
+      @on_po_registered&.call(po)
+
+      po
+    end
+
+    # Load a prompt object by name from the objects directory.
+    # @param name [String] Name of the prompt object (without .md extension)
+    # @return [PromptObject]
+    def load_by_name(name)
+      path = File.join(@objects_dir, "#{name}.md")
+      load_prompt_object(path)
+    end
+
+    # Load all prompt objects that a capability depends on.
+    # @param capability [PromptObject] The capability to load dependencies for
+    def load_dependencies(capability)
+      return unless capability.is_a?(PromptObject)
+
+      deps = capability.config["capabilities"] || []
+      deps.each do |dep_name|
+        next if @registry.exists?(dep_name)
+
+        # Try to load as a prompt object
+        path = File.join(@objects_dir, "#{dep_name}.md")
+        if File.exist?(path)
+          load_prompt_object(path)
+        end
+      end
+    end
+
+    # Get a capability by name (prompt object or primitive).
+    # @param name [String] The capability name
+    # @return [Capability, nil]
+    def get(name)
+      @registry.get(name)
+    end
+
+    # List all loaded prompt objects.
+    # @return [Array<String>]
+    def loaded_objects
+      @registry.prompt_objects.map(&:name)
+    end
+
+    # List all registered primitives.
+    # @return [Array<String>]
+    def primitives
+      @registry.primitives.map(&:name)
+    end
+
+    private
+
+    # Register built-in primitive capabilities.
+    def register_primitives
+      @registry.register(Primitives::ReadFile.new)
+      @registry.register(Primitives::ListFiles.new)
+      @registry.register(Primitives::WriteFile.new)
+      @registry.register(Primitives::HttpGet.new)
+    end
+
+    # Register universal capabilities (available to all prompt objects).
+    def register_universal_capabilities
+      @registry.register(Universal::AskHuman.new)
+      @registry.register(Universal::Think.new)
+      @registry.register(Universal::CreateCapability.new)
+      @registry.register(Universal::AddCapability.new)
+      @registry.register(Universal::ListCapabilities.new)
+      @registry.register(Universal::ListPrimitives.new)
+      @registry.register(Universal::AddPrimitive.new)
+      @registry.register(Universal::CreatePrimitive.new)
+      @registry.register(Universal::VerifyPrimitive.new)
+      @registry.register(Universal::ModifyPrimitive.new)
+      @registry.register(Universal::RequestPrimitive.new)
+    end
+  end
+
+  # Backwards compatibility alias (Environment was renamed to Runtime).
+  # Use Runtime for new code; Environment is preserved for existing callers.
+  Environment = Runtime
+end

data/lib/prompt_objects/human_queue.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module PromptObjects
+  # Represents a pending request for human input
+  class HumanRequest
+    attr_reader :id, :capability, :question, :options, :created_at
+    attr_accessor :response
+
+    def initialize(capability:, question:, options: nil)
+      @id = SecureRandom.uuid
+      @capability = capability
+      @question = question
+      @options = options
+      @created_at = Time.now
+      @response = nil
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+    end
+
+    def pending?
+      @response.nil?
+    end
+
+    def age
+      Time.now - @created_at
+    end
+
+    def age_string
+      seconds = age.to_i
+      if seconds < 60
+        "#{seconds}s"
+      elsif seconds < 3600
+        "#{seconds / 60}m"
+      else
+        "#{seconds / 3600}h"
+      end
+    end
+
+    # Called by the background thread to wait for response
+    def wait_for_response
+      @mutex.synchronize do
+        @condition.wait(@mutex) while @response.nil?
+        @response
+      end
+    end
+
+    # Called by the UI thread when human responds
+    def respond!(value)
+      @mutex.synchronize do
+        @response = value
+        @condition.broadcast
+      end
+    end
+  end
+
+  # Queue for managing pending human requests across all POs
+  class HumanQueue
+    attr_reader :pending
+
+    def initialize
+      @pending = []
+      @subscribers = []
+      @mutex = Mutex.new
+    end
+
+    # Add a request to the queue
+    # Returns the HumanRequest object
+    def enqueue(capability:, question:, options: nil)
+      request = HumanRequest.new(
+        capability: capability,
+        question: question,
+        options: options
+      )
+
+      @mutex.synchronize do
+        @pending << request
+      end
+
+      notify_subscribers(:added, request)
+      request
+    end
+
+    # Respond to a pending request by ID
+    def respond(request_id, value)
+      request = nil
+      @mutex.synchronize do
+        request = @pending.find { |r| r.id == request_id }
+        return unless request
+
+        @pending.delete(request)
+      end
+
+      notify_subscribers(:resolved, request)
+      request.respond!(value)
+    end
+
+    # Get pending requests for a specific capability
+    def pending_for(capability_name)
+      @mutex.synchronize do
+        @pending.select { |r| r.capability == capability_name }
+      end
+    end
+
+    # Get count of pending requests per capability
+    def pending_counts
+      @mutex.synchronize do
+        @pending.group_by(&:capability).transform_values(&:count)
+      end
+    end
+
+    # Total pending count
+    def count
+      @mutex.synchronize { @pending.length }
+    end
+
+    # Subscribe to queue events
+    # Callback receives (event, request) where event is :added or :resolved
+    def subscribe(&block)
+      @subscribers << block
+    end
+
+    def unsubscribe(block)
+      @subscribers.delete(block)
+    end
+
+    # Get all pending requests (thread-safe copy)
+    def all_pending
+      @mutex.synchronize { @pending.dup }
+    end
+
+    private
+
+    def notify_subscribers(event, request)
+      @subscribers.each do |s|
+        s.call(event, request)
+      rescue StandardError => e
+        # Don't let subscriber errors break the queue
+        warn "HumanQueue subscriber error: #{e.message}"
+      end
+    end
+  end
+end