prompt_objects 0.5.0 → 0.7.0

data/exe/prompt_objects_mcp

@@ -1,9 +1,11 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "bundler/setup"
-require_relative "../lib/prompt_objects"
-require_relative "../lib/prompt_objects/mcp/server"
+# Add lib to the load path for development; installed gems already expose it.
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "prompt_objects"
+require "prompt_objects/mcp/server"
 
 # Parse command line options
 objects_dir = ENV["PROMPT_OBJECTS_DIR"] || "objects"

data/lib/prompt_objects/capability.rb

@@ -11,6 +11,39 @@ module PromptObjects
       @state = :idle
     end
 
+    class << self
+      def execution_policy(parallel_safe: false, side_effect: :exclusive, resource_keys: nil, workload: :blocking)
+        @execution_policy = Execution::Policy.new(
+          parallel_safe: parallel_safe,
+          side_effect: side_effect,
+          resource_keys: resource_keys,
+          workload: workload
+        )
+      end
+
+      def execution_policy_definition
+        return @execution_policy if defined?(@execution_policy) && @execution_policy
+
+        superclass.respond_to?(:execution_policy_definition) ? superclass.execution_policy_definition : nil
+      end
+    end
+
+    def resolved_execution_policy(arguments:, context:)
+      policy = execution_policy_definition
+      policy.resolve(arguments: arguments, context: context, capability: self)
+    end
+
+    def execution_policy_signature
+      execution_policy_definition.signature(self)
+    end
+
+    def execution_policy_definition
+      self.class.execution_policy_definition || Execution::Policy.new(
+        parallel_safe: false,
+        side_effect: :exclusive
+      )
+    end
+
     # Handle a message and return a response.
     # @param message [String, Hash] The incoming message
     # @param context [Context] Execution context with environment reference

data/lib/prompt_objects/cli/diagnostics_command.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module PromptObjects
+  module CLI
+    class DiagnosticsCommand
+      def run(args)
+        json = args.delete("--json")
+        return help if args.include?("--help") || args.include?("-h")
+
+        env_name = args.first
+        raise Error, "environment name required" unless env_name
+
+        env_path = Helpers.resolve_environment(env_name)
+        raise Error, "environment '#{env_name}' not found" unless env_path
+
+        data = server_snapshot(env_path) || local_snapshot(env_path)
+        json ? puts(JSON.pretty_generate(data)) : print_summary(data)
+      rescue Error => e
+        $stderr.puts "Error: #{e.message}"
+        1
+      end
+
+      def help
+        puts <<~HELP
+          Usage: #{Helpers.program_name} diagnostics <environment> [--json]
+
+          Show content-free scheduler, timing, failure, usage, and database health metrics.
+        HELP
+      end
+
+      private
+
+      def server_snapshot(env_path)
+        require "prompt_objects/server"
+        server = PromptObjects::Server.read_server_file(env_path)
+        return nil unless server
+
+        uri = URI("http://#{server[:host]}:#{server[:port]}/api/diagnostics")
+        JSON.parse(Net::HTTP.get(uri), symbolize_names: true)
+      rescue Errno::ECONNREFUSED
+        nil
+      end
+
+      def local_snapshot(env_path)
+        path = File.join(env_path, "sessions.db")
+        raise Error, "sessions.db not found" unless File.file?(path)
+
+        store = Session::Store.new(path)
+        Operations::Diagnostics.new(store).snapshot
+      ensure
+        store&.close
+      end
+
+      def print_summary(data)
+        puts "Runtime diagnostics (#{data[:generated_at]})"
+        puts "  database: #{data.dig(:database, :bytes)} bytes, #{data.dig(:database, :integrity)}"
+        puts "  scheduler: #{data.dig(:scheduler, :running) || 0} running, #{data.dig(:scheduler, :queued) || 0} queued"
+        puts "  runs: #{data.dig(:counts, :runs)} total, #{data.dig(:runs, :active)} active, #{data.dig(:runs, :failure_rate)} failure rate"
+        puts "  queue wait: #{data.dig(:runs, :queue_wait_ms, :average)} ms avg / #{data.dig(:runs, :queue_wait_ms, :p95)} ms p95"
+        puts "  run duration: #{data.dig(:runs, :duration_ms, :average)} ms avg / #{data.dig(:runs, :duration_ms, :p95)} ms p95"
+        puts "  tool duration: #{data.dig(:tools, :duration_ms, :average)} ms avg / #{data.dig(:tools, :duration_ms, :p95)} ms p95"
+      end
+    end
+  end
+end

data/lib/prompt_objects/cli/env_command.rb

@@ -0,0 +1,435 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module CLI
+    # `env` command: manage environments (list, create, info, export, import,
+    # archive, restore, clone, delete, default).
+    class EnvCommand
+      def initialize(manager: nil)
+        @manager = manager || Env::Manager.new
+      end
+
+      # Run the env subcommand.
+      # @param args [Array<String>] Arguments after 'env'
+      def run(args)
+        subcommand = args.shift || "list"
+
+        case subcommand
+        when "list", "ls"
+          list(args)
+        when "create", "new"
+          create(args)
+        when "info"
+          info(args)
+        when "export"
+          export(args)
+        when "import"
+          import(args)
+        when "archive"
+          archive(args)
+        when "restore"
+          restore(args)
+        when "clone", "cp"
+          clone(args)
+        when "delete"
+          delete(args)
+        when "default"
+          set_default(args)
+        else
+          puts "Unknown env command: #{subcommand}"
+          puts
+          help
+          exit 1
+        end
+      end
+
+      def list(args = [])
+        @manager.setup!
+        envs = @manager.list_with_manifests
+
+        if envs.empty?
+          puts "No environments found."
+          puts "Create one with: #{prog} env create <name>"
+          return
+        end
+
+        default = @manager.default_environment
+
+        if args.include?("-v") || args.include?("--verbose")
+          puts "Environments (#{envs.size}):"
+          puts
+          envs.each do |manifest|
+            default_marker = manifest.name == default ? " (default)" : ""
+            last_opened = manifest.last_opened&.strftime("%Y-%m-%d") || "never"
+            puts "  #{manifest.icon} #{manifest.name}#{default_marker}"
+            puts "    #{manifest.description}" if manifest.description
+            puts "    Last opened: #{last_opened}, Objects: #{manifest.stats['po_count']}"
+            puts
+          end
+          return
+        end
+
+        # Concise: one line per environment, aligned for scanning.
+        width = [envs.map { |m| m.name.length }.max, 32].min
+        archived = @manager.list_archived.size
+
+        header = "Environments (#{envs.size})"
+        header += "  ·  #{archived} archived" if archived.positive?
+        puts header
+        puts
+        envs.each do |m|
+          name = m.name.ljust(width)
+          last = (m.last_opened&.strftime("%Y-%m-%d") || "never").ljust(10)
+          pos = (m.stats["po_count"] || 0).to_s.rjust(2)
+          marker = m.name == default ? "  (default)" : ""
+          puts "  #{name}  #{last}  #{pos} POs#{marker}"
+        end
+        puts
+        puts "Details: env list -v   ·   Delete: env delete <name>... --permanent"
+      end
+
+      def create(args)
+        name = args.shift
+        unless name
+          puts "Usage: #{prog} env create <name> [--template <template>]"
+          exit 1
+        end
+
+        template = nil
+        args.each_with_index do |arg, i|
+          if arg == "--template" || arg == "-t"
+            template = args[i + 1]
+          end
+        end
+
+        @manager.setup!
+
+        path = @manager.create(name: name, template: template)
+        puts "Created environment: #{name}"
+        puts "Location: #{path}"
+
+        # Print dependency info if template declares gems
+        manifest = Env::Manifest.load_from_dir(path)
+        if manifest.dependencies&.dig("gems")&.any?
+          vendor_dir = File.join(path, "vendor")
+          if Dir.exist?(vendor_dir) && !Dir.empty?(vendor_dir)
+            puts "\nBundled dependencies (vendored):"
+            manifest.dependencies["gems"].each do |gem_info|
+              puts "  #{gem_info['name']} — #{gem_info['purpose']}"
+            end
+          else
+            puts "\nRequired dependencies (not vendored — install manually):"
+            manifest.dependencies["gems"].each do |gem_info|
+              puts "  gem install #{gem_info['name']}  # #{gem_info['purpose']}"
+            end
+          end
+        end
+
+        if @manager.list.size == 1
+          @manager.set_default_environment(name)
+          puts "Set as default environment."
+        end
+      end
+
+      def info(args)
+        name = args.shift || @manager.default_environment
+        unless name
+          puts "Usage: #{prog} env info <name>"
+          exit 1
+        end
+
+        manifest = @manager.manifest_for(name)
+        unless manifest
+          puts "Environment '#{name}' not found."
+          exit 1
+        end
+
+        path = @manager.environment_path(name)
+        objects = Dir.glob(File.join(path, "objects", "*.md")).map { |f| File.basename(f, ".md") }
+        primitives = Dir.glob(File.join(path, "primitives", "*.rb")).map { |f| File.basename(f, ".rb") }
+
+        puts manifest.info
+        puts
+        puts "  Location: #{path}"
+        puts "  Objects: #{objects.join(', ')}" if objects.any?
+        puts "  Custom primitives: #{primitives.join(', ')}" if primitives.any?
+        puts
+
+        if Env::Git.repo?(path)
+          commits = Env::Git.commit_count(path)
+          dirty = Env::Git.dirty?(path)
+          puts "  Git: #{commits} commits#{dirty ? ' (uncommitted changes)' : ''}"
+        end
+      end
+
+      def export(args)
+        @manager.setup!
+
+        # Parse arguments
+        name = nil
+        output = nil
+
+        i = 0
+        while i < args.length
+          case args[i]
+          when "-o", "--output"
+            output = args[i + 1]
+            i += 1
+          else
+            name ||= args[i]
+          end
+          i += 1
+        end
+
+        # Default to current directory name if no output specified
+        name ||= @manager.default_environment
+        unless name
+          puts "Usage: #{prog} env export <name> [-o output.dump]"
+          exit 1
+        end
+
+        unless @manager.environment_exists?(name)
+          puts "Environment '#{name}' not found."
+          exit 1
+        end
+
+        output ||= "#{name}.dump"
+        env_path = @manager.environment_path(name)
+
+        exporter = Env::Exporter.new(env_path)
+        result = exporter.export(output)
+
+        if result[:success]
+          puts "Exported '#{name}' to: #{result[:path]}"
+          puts
+          puts "Stats:"
+          puts "  Commits: #{result[:stats][:commits]}"
+          puts "  Objects: #{result[:stats][:objects]}"
+          puts "  Primitives: #{result[:stats][:primitives]}"
+        else
+          puts "Export failed: #{result[:error]}"
+          exit 1
+        end
+      end
+
+      def import(args)
+        @manager.setup!
+
+        # Parse arguments
+        bundle_path = nil
+        import_as = nil
+        trust = false
+
+        i = 0
+        while i < args.length
+          case args[i]
+          when "--as"
+            import_as = args[i + 1]
+            i += 1
+          when "--trust"
+            trust = true
+          else
+            bundle_path ||= args[i]
+          end
+          i += 1
+        end
+
+        unless bundle_path
+          puts "Usage: #{prog} env import <bundle.dump> [--as <name>] [--trust]"
+          puts
+          puts "Options:"
+          puts "  --as <name>   Import with a different name"
+          puts "  --trust       Trust custom primitives (skip sandbox warnings)"
+          exit 1
+        end
+
+        importer = Env::Importer.new(bundle_path)
+
+        # First, inspect and show what's in the bundle
+        info = importer.inspect_bundle
+        unless info.valid
+          puts "Invalid bundle: #{info.error}"
+          exit 1
+        end
+
+        puts "Bundle contents:"
+        puts "  Name: #{info.name}"
+        puts "  Description: #{info.description}" if info.description
+        puts "  Objects: #{info.objects.join(', ')}" if info.objects.any?
+        puts "  Primitives: #{info.primitives.join(', ')}" if info.primitives.any?
+        puts "  Commits: #{info.commits}"
+        puts
+
+        # Warn about primitives
+        if info.primitives.any? && !trust
+          puts "⚠️  WARNING: This bundle contains custom primitives."
+          puts "Custom primitives can execute arbitrary Ruby code."
+          puts "Review the code before running, or use --trust to skip this warning."
+          puts
+        end
+
+        # Import
+        import_name = import_as || info.name
+        result = importer.import(manager: @manager, name: import_name, trust_primitives: trust)
+
+        if result[:success]
+          puts "Imported as '#{result[:name]}'"
+          puts "Location: #{result[:path]}"
+
+          if result[:warnings].any?
+            puts
+            result[:warnings].each { |w| puts w }
+          end
+        else
+          puts "Import failed: #{result[:error]}"
+          exit 1
+        end
+      end
+
+      def archive(args)
+        name = args.shift
+        unless name
+          puts "Usage: #{prog} env archive <name>"
+          exit 1
+        end
+
+        path = @manager.archive(name)
+        puts "Archived environment '#{name}' to:"
+        puts "  #{path}"
+      end
+
+      def restore(args)
+        archived_name = args.shift
+        unless archived_name
+          # Show available archived environments
+          archived = @manager.list_archived
+          if archived.empty?
+            puts "No archived environments."
+          else
+            puts "Archived environments:"
+            archived.each { |name| puts "  - #{name}" }
+            puts
+            puts "Usage: #{prog} env restore <archived_name> [--as <new_name>]"
+          end
+          return
+        end
+
+        restore_as = nil
+        args.each_with_index do |arg, i|
+          restore_as = args[i + 1] if arg == "--as"
+        end
+
+        path = @manager.restore(archived_name, restore_as: restore_as)
+        puts "Restored to: #{path}"
+      end
+
+      def clone(args)
+        source = args.shift
+        target = args.shift
+
+        unless source && target
+          puts "Usage: #{prog} env clone <source> <target>"
+          exit 1
+        end
+
+        path = @manager.clone(source, target)
+        puts "Cloned '#{source}' to '#{target}'"
+        puts "Location: #{path}"
+      end
+
+      def delete(args)
+        permanent = args.delete("--permanent")
+        names = args
+
+        if names.empty?
+          puts "Usage: #{prog} env delete <name> [<name>...] --permanent"
+          puts
+          puts "Permanently deletes environments (active or archived) and all their data."
+          puts "For a recoverable flow, use `env archive <name>` instead."
+          return
+        end
+
+        unless permanent
+          puts "This permanently deletes #{names.size} environment#{names.size == 1 ? '' : 's'} and cannot be undone:"
+          names.each { |n| puts "  - #{n}" }
+          puts
+          puts "Re-run with --permanent to confirm."
+          return
+        end
+
+        names.each do |name|
+          if @manager.environment_exists?(name)
+            @manager.destroy(name)
+            puts "Deleted: #{name}"
+          elsif @manager.list_archived.include?(name)
+            @manager.delete_archived(name)
+            puts "Deleted (archived): #{name}"
+          else
+            puts "Not found: #{name}"
+          end
+        rescue => e
+          puts "Failed to delete #{name}: #{e.message}"
+        end
+      end
+
+      def set_default(args)
+        name = args.shift
+        unless name
+          current = @manager.default_environment
+          if current
+            puts "Current default: #{current}"
+          else
+            puts "No default environment set."
+          end
+          puts
+          puts "Usage: #{prog} env default <name>"
+          return
+        end
+
+        @manager.set_default_environment(name)
+        puts "Default environment set to: #{name}"
+      end
+
+      def help
+        puts <<~HELP
+          Environment management commands:
+
+            #{prog} env list              List all environments (one line each)
+              -v, --verbose                     Show full details per environment
+            #{prog} env create <name>    Create new environment
+              --template, -t <template>         Use one of the templates listed below
+            #{prog} env info <name>      Show environment details
+            #{prog} env export <name>    Export environment as .dump bundle
+              -o, --output <file>               Output file path
+            #{prog} env import <file>    Import environment from .dump bundle
+              --as <name>                       Import with different name
+              --trust                           Trust custom primitives
+            #{prog} env archive <name>   Archive (soft delete) environment
+            #{prog} env restore <name>   Restore archived environment
+              --as <new_name>                   Restore with different name
+            #{prog} env clone <src> <dest>  Clone environment
+            #{prog} env default <name>   Set default environment
+            #{prog} env delete <name>... --permanent  Permanently delete (active or archived; accepts multiple)
+
+          Available templates:
+            basic      - No capabilities, learns as needed (great for demos!)
+            minimal    - Basic assistant with file reading
+            developer  - Code review, debugging, testing specialists
+            writer     - Editor, researcher for content creation
+            empty      - Bootstrap assistant only
+            arc-agi-1  - ARC-AGI-1 challenge solving with grid primitives
+            arc-agi-3  - Interactive ARC-AGI-3 environment with remote API
+            chiptune   - Chiptune music composition via Sonic Pi (genre-specific)
+            music      - Open-ended music composition via Sonic Pi (any genre)
+            music-pro  - Expressive live-pattern composition via Sonic Pi
+        HELP
+      end
+
+      private
+
+      def prog
+        Helpers.program_name
+      end
+    end
+  end
+end

data/lib/prompt_objects/cli/events_command.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "json"
+
+module PromptObjects
+  module CLI
+    # `events` command: show recent events from the message bus.
+    class EventsCommand
+      def run(args)
+        options = { count: 50, session_id: nil, json: false }
+        positional = []
+        skip_next = false
+
+        args.each_with_index do |arg, i|
+          if skip_next
+            skip_next = false
+            next
+          end
+
+          case arg
+          when "--session"
+            options[:session_id] = args[i + 1]
+            skip_next = true
+          when "--count"
+            options[:count] = args[i + 1].to_i
+            skip_next = true
+          when "--json"
+            options[:json] = true
+          when "--help", "-h"
+            help
+            exit 0
+          else
+            positional << arg
+          end
+        end
+
+        env_name = positional[0]
+        unless env_name
+          puts "Error: environment name required"
+          puts "Run '#{Helpers.program_name} events --help' for usage"
+          exit 1
+        end
+
+        env_path = Helpers.resolve_environment(env_name)
+        unless env_path
+          $stderr.puts "Error: environment '#{env_name}' not found"
+          exit 1
+        end
+
+        # Check for running server
+        require "prompt_objects/server"
+        server_info = PromptObjects::Server.read_server_file(env_path)
+
+        if server_info
+          show_via_http(server_info, options)
+        else
+          show_standalone(env_path, options)
+        end
+      end
+
+      def help
+        prog = Helpers.program_name
+        puts <<~HELP
+          Usage: #{prog} events [options] <environment>
+
+          Show recent events from the message bus.
+
+          Arguments:
+            environment  Environment name or path
+
+          Options:
+            --session ID     Show events for a specific session
+            --count N        Number of events to show (default: 50)
+            --json           Output as JSON
+            --help, -h       Show this help
+
+          Examples:
+            #{prog} events my-env
+            #{prog} events my-env --session abc-123
+            #{prog} events my-env --count 100 --json
+        HELP
+      end
+
+      private
+
+      def show_via_http(server_info, options)
+        require "net/http"
+        require "uri"
+
+        if options[:session_id]
+          uri = URI("http://#{server_info[:host]}:#{server_info[:port]}/api/events/session/#{options[:session_id]}")
+        else
+          uri = URI("http://#{server_info[:host]}:#{server_info[:port]}/api/events?count=#{options[:count]}")
+        end
+
+        response = Net::HTTP.get(uri)
+        data = JSON.parse(response)
+
+        if options[:json]
+          puts JSON.pretty_generate(data)
+        else
+          Helpers.print_events(data["events"] || [])
+        end
+      rescue Errno::ECONNREFUSED
+        $stderr.puts "Error: Server not responding"
+        exit 1
+      end
+
+      def show_standalone(env_path, options)
+        db_path = File.join(env_path, "sessions.db")
+        unless File.exist?(db_path)
+          puts "No event history (sessions.db not found)"
+          exit 0
+        end
+
+        store = PromptObjects::Session::Store.new(db_path)
+
+        events = if options[:session_id]
+          store.get_events(session_id: options[:session_id])
+        else
+          store.get_recent_events(options[:count])
+        end
+
+        if options[:json]
+          formatted = events.map do |e|
+            {
+              id: e[:id],
+              from: e[:from],
+              to: e[:to],
+              summary: e[:summary],
+              message: e[:message],
+              timestamp: e[:timestamp]&.iso8601,
+              session_id: e[:session_id]
+            }
+          end
+          puts JSON.pretty_generate(formatted)
+        else
+          Helpers.print_events(events)
+        end
+
+        store.close
+      end
+    end
+  end
+end