simple_acp 0.0.1

data/lib/simple_acp/models/run.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+module SimpleAcp
+  module Models
+    # Represents a single agent execution.
+    #
+    # Tracks the lifecycle of an agent run from creation through completion,
+    # including status, output messages, errors, and timing.
+    #
+    # == Status Lifecycle
+    #
+    # - created -> in_progress -> completed | failed | cancelled | awaiting
+    # - awaiting -> in_progress (on resume)
+    # - cancelling -> cancelled
+    class Run < Base
+      # @!attribute [r] run_id
+      #   @return [String] unique UUID for this run
+      attribute :run_id, required: true
+
+      # @!attribute [r] agent_name
+      #   @return [String] name of the agent being executed
+      attribute :agent_name, required: true
+
+      # @!attribute [r] session_id
+      #   @return [String, nil] optional session ID
+      attribute :session_id
+
+      # @!attribute [r] status
+      #   @return [String] current status (created, in-progress, completed, failed, cancelled, awaiting)
+      attribute :status, default: Types::RunStatus::CREATED
+
+      # @!attribute [r] await_request
+      #   @return [AwaitRequest, nil] request for client input (when awaiting)
+      attribute :await_request
+
+      # @!attribute [r] output
+      #   @return [Array<Message>] output messages from the agent
+      attribute :output, default: -> { [] }
+
+      # @!attribute [r] error
+      #   @return [Error, nil] error details if failed
+      attribute :error
+
+      # @!attribute [r] created_at
+      #   @return [Time, nil] when the run was created
+      attribute :created_at
+
+      # @!attribute [r] finished_at
+      #   @return [Time, nil] when the run finished (completed, failed, or cancelled)
+      attribute :finished_at
+
+      def initialize(**kwargs)
+        super
+        @run_id ||= Types.generate_uuid
+        @output ||= []
+        @created_at ||= Time.now
+      end
+
+      # Create from a hash (JSON deserialization).
+      #
+      # @param hash [Hash, nil] run data
+      # @return [Run, nil] the run or nil
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        instance = allocate
+        instance.send(:initialize_from_hash, hash)
+        instance
+      end
+
+      # Check if the run is in a terminal state.
+      #
+      # @return [Boolean] true if completed, failed, or cancelled
+      def terminal?
+        Types::RunStatus.terminal?(@status)
+      end
+
+      # Check if the run is currently executing.
+      #
+      # @return [Boolean] true if in_progress
+      def in_progress?
+        @status == Types::RunStatus::IN_PROGRESS
+      end
+
+      # Check if the run is waiting for client input.
+      #
+      # @return [Boolean] true if awaiting
+      def awaiting?
+        @status == Types::RunStatus::AWAITING
+      end
+
+      # Check if the run completed successfully.
+      #
+      # @return [Boolean] true if completed
+      def completed?
+        @status == Types::RunStatus::COMPLETED
+      end
+
+      # Check if the run failed.
+      #
+      # @return [Boolean] true if failed
+      def failed?
+        @status == Types::RunStatus::FAILED
+      end
+
+      # Check if the run was cancelled.
+      #
+      # @return [Boolean] true if cancelled
+      def cancelled?
+        @status == Types::RunStatus::CANCELLED
+      end
+
+      # Check if the run is being cancelled.
+      #
+      # @return [Boolean] true if cancelling
+      def cancelling?
+        @status == Types::RunStatus::CANCELLING
+      end
+
+      # Transition to in_progress status.
+      #
+      # @return [self] for chaining
+      def start!
+        @status = Types::RunStatus::IN_PROGRESS
+        self
+      end
+
+      # Transition to awaiting status.
+      #
+      # @param request [AwaitRequest] the request for client input
+      # @return [self] for chaining
+      def await!(request)
+        @status = Types::RunStatus::AWAITING
+        @await_request = request
+        self
+      end
+
+      # Transition to completed status.
+      #
+      # @param output [Array<Message>, nil] optional output messages
+      # @return [self] for chaining
+      def complete!(output = nil)
+        @status = Types::RunStatus::COMPLETED
+        @output = output if output
+        @finished_at = Time.now
+        self
+      end
+
+      # Transition to failed status.
+      #
+      # @param error [Error, String] the error or error message
+      # @return [self] for chaining
+      def fail!(error)
+        @status = Types::RunStatus::FAILED
+        @error = error.is_a?(Error) ? error : Error.server_error(error.to_s)
+        @finished_at = Time.now
+        self
+      end
+
+      # Transition to cancelling status.
+      #
+      # @return [self] for chaining
+      def cancel!
+        @status = Types::RunStatus::CANCELLING
+        self
+      end
+
+      # Transition to cancelled status.
+      #
+      # @return [self] for chaining
+      def cancelled!
+        @status = Types::RunStatus::CANCELLED
+        @finished_at = Time.now
+        self
+      end
+
+      # Add a message to the output.
+      #
+      # @param message [Message, Hash] the message to add
+      # @return [self] for chaining
+      def add_output(message)
+        @output << (message.is_a?(Message) ? message : Message.from_hash(message))
+        self
+      end
+
+      # Raise an exception if the run failed.
+      #
+      # @return [self] if not failed
+      # @raise [RunError] if failed
+      def raise_for_status!
+        return self unless failed?
+
+        raise SimpleAcp::RunError, @error&.message || "Run failed"
+      end
+
+      # Validate the run.
+      #
+      # @return [Boolean] true if run_id, agent_name, and status are valid
+      def valid?
+        return false unless Types.valid_uuid?(@run_id)
+        return false unless Types.valid_agent_name?(@agent_name)
+        return false unless Types::RunStatus.valid?(@status)
+
+        true
+      end
+
+      private
+
+      def initialize_from_hash(hash)
+        @run_id = hash["run_id"] || hash[:run_id]
+        @agent_name = hash["agent_name"] || hash[:agent_name]
+        @session_id = hash["session_id"] || hash[:session_id]
+        @status = hash["status"] || hash[:status] || Types::RunStatus::CREATED
+        @created_at = parse_time(hash["created_at"] || hash[:created_at])
+        @finished_at = parse_time(hash["finished_at"] || hash[:finished_at])
+
+        output_data = hash["output"] || hash[:output] || []
+        @output = output_data.map { |m| Message.from_hash(m) }
+
+        if hash["error"] || hash[:error]
+          @error = Error.from_hash(hash["error"] || hash[:error])
+        end
+
+        if hash["await_request"] || hash[:await_request]
+          @await_request = AwaitRequest.from_hash(hash["await_request"] || hash[:await_request])
+        end
+      end
+
+      def parse_time(value)
+        return nil if value.nil?
+        return value if value.is_a?(Time)
+
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    # Request body for creating a run
+    class RunCreateRequest < Base
+      attribute :agent_name, required: true
+      attribute :input, required: true
+      attribute :mode
+      attribute :session_id
+      attribute :session
+
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        instance = super
+
+        input_data = hash["input"] || hash[:input] || []
+        instance.input = input_data.map { |m| Message.from_hash(m) }
+
+        if hash["session"] || hash[:session]
+          instance.session = Session.from_hash(hash["session"] || hash[:session])
+        end
+
+        instance
+      end
+
+      def valid?
+        return false unless Types.valid_agent_name?(@agent_name)
+        return false if @input.nil? || @input.empty?
+        return false if @mode && !Types::RunMode.valid?(@mode)
+
+        true
+      end
+    end
+
+    # Request body for resuming a run
+    class RunResumeRequest < Base
+      attribute :run_id, required: true
+      attribute :await_resume, required: true
+      attribute :mode, required: true
+
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        instance = super
+
+        if hash["await_resume"] || hash[:await_resume]
+          instance.await_resume = AwaitResume.from_hash(hash["await_resume"] || hash[:await_resume])
+        end
+
+        instance
+      end
+
+      def valid?
+        return false unless Types.valid_uuid?(@run_id)
+        return false if @await_resume.nil?
+        return false unless Types::RunMode.valid?(@mode)
+
+        true
+      end
+    end
+  end
+end

data/lib/simple_acp/models/session.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module SimpleAcp
+  module Models
+    # Maintains state and conversation history across interactions.
+    #
+    # Sessions allow agents to maintain context between requests,
+    # storing both conversation history and arbitrary state data.
+    #
+    # @example Using sessions with the client
+    #   client.use_session("my-session")
+    #   client.run_sync(agent: "counter", input: "increment")  # Count: 1
+    #   client.run_sync(agent: "counter", input: "increment")  # Count: 2
+    class Session < Base
+      # @!attribute [r] id
+      #   @return [String] unique session ID
+      attribute :id, required: true
+
+      # @!attribute [r] history
+      #   @return [Array<Message>] conversation history
+      attribute :history, default: -> { [] }
+
+      # @!attribute [r] state
+      #   @return [Object, nil] arbitrary state data
+      attribute :state
+
+      def initialize(**kwargs)
+        super
+        @id ||= Types.generate_uuid
+        @history ||= []
+      end
+
+      # Create from a hash (JSON deserialization).
+      #
+      # @param hash [Hash, nil] session data
+      # @return [Session, nil] the session or nil
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        instance = allocate
+        instance.send(:initialize_from_hash, hash)
+        instance
+      end
+
+      # Create a new session with a generated ID.
+      #
+      # @return [Session] new session
+      def self.create
+        new(id: Types.generate_uuid)
+      end
+
+      # Add a message to the conversation history.
+      #
+      # @param message [Message, Hash] the message to add
+      # @return [self] for chaining
+      def add_to_history(message)
+        @history << (message.is_a?(Message) ? message : Message.from_hash(message))
+        self
+      end
+
+      # Clear all conversation history.
+      #
+      # @return [self] for chaining
+      def clear_history!
+        @history = []
+        self
+      end
+
+      # Set the session state.
+      #
+      # @param state_data [Object] arbitrary state data
+      # @return [self] for chaining
+      def set_state(state_data)
+        @state = state_data
+        self
+      end
+
+      # Clear the session state.
+      #
+      # @return [self] for chaining
+      def clear_state!
+        @state = nil
+        self
+      end
+
+      # Get the number of messages in history.
+      #
+      # @return [Integer] message count
+      def message_count
+        @history.length
+      end
+
+      # Check if the session has no history or state.
+      #
+      # @return [Boolean] true if no history and no state
+      def empty?
+        @history.empty? && @state.nil?
+      end
+
+      # Validate the session.
+      #
+      # @return [Boolean] true if ID is a valid UUID
+      def valid?
+        Types.valid_uuid?(@id)
+      end
+
+      private
+
+      def initialize_from_hash(hash)
+        @id = hash["id"] || hash[:id]
+        @state = hash["state"] || hash[:state]
+
+        history_data = hash["history"] || hash[:history] || []
+        @history = history_data.map do |item|
+          item.is_a?(Message) ? item : Message.from_hash(item)
+        end
+      end
+    end
+
+    # Response for getting session details
+    class SessionResponse < Base
+      attribute :id
+      attribute :history_count
+      attribute :has_state
+      attribute :created_at
+
+      def self.from_session(session)
+        new(
+          id: session.id,
+          history_count: session.history.length,
+          has_state: !session.state.nil?,
+          created_at: Time.now
+        )
+      end
+    end
+  end
+end

data/lib/simple_acp/models/types.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module SimpleAcp
+  module Models
+    # Type definitions, constants, and validations for ACP.
+    #
+    # Contains all the enumerated types and validation helpers
+    # used throughout the protocol.
+    module Types
+      # Agent name must follow RFC 1123 DNS label format
+      AGENT_NAME_PATTERN = /\A[a-z0-9]([-a-z0-9]*[a-z0-9])?\z/
+
+      # Maximum length for agent names
+      AGENT_NAME_MAX_LENGTH = 63
+
+      # Run execution modes.
+      module RunMode
+        # Synchronous execution (blocks until complete)
+        SYNC = "sync"
+        # Asynchronous execution (returns immediately)
+        ASYNC = "async"
+        # Streaming execution (SSE events)
+        STREAM = "stream"
+
+        # All valid modes
+        ALL = [SYNC, ASYNC, STREAM].freeze
+
+        # Check if a mode is valid.
+        #
+        # @param mode [String] mode to check
+        # @return [Boolean] true if valid
+        def self.valid?(mode)
+          ALL.include?(mode)
+        end
+      end
+
+      # Run status values.
+      module RunStatus
+        # Run created but not started
+        CREATED = "created"
+        # Run is executing
+        IN_PROGRESS = "in-progress"
+        # Run is waiting for client input
+        AWAITING = "awaiting"
+        # Run is being cancelled
+        CANCELLING = "cancelling"
+        # Run was cancelled
+        CANCELLED = "cancelled"
+        # Run completed successfully
+        COMPLETED = "completed"
+        # Run failed with error
+        FAILED = "failed"
+
+        # All valid statuses
+        ALL = [CREATED, IN_PROGRESS, AWAITING, CANCELLING, CANCELLED, COMPLETED, FAILED].freeze
+
+        # Terminal (final) statuses
+        TERMINAL = [COMPLETED, FAILED, CANCELLED].freeze
+
+        # Check if a status is valid.
+        #
+        # @param status [String] status to check
+        # @return [Boolean] true if valid
+        def self.valid?(status)
+          ALL.include?(status)
+        end
+
+        # Check if a status is terminal (run is finished).
+        #
+        # @param status [String] status to check
+        # @return [Boolean] true if terminal
+        def self.terminal?(status)
+          TERMINAL.include?(status)
+        end
+      end
+
+      # Link types for agent metadata.
+      module LinkType
+        # Link to source code repository
+        SOURCE_CODE = "source-code"
+        # Link to container image
+        CONTAINER_IMAGE = "container-image"
+        # Link to homepage
+        HOMEPAGE = "homepage"
+        # Link to documentation
+        DOCUMENTATION = "documentation"
+
+        # All valid link types
+        ALL = [SOURCE_CODE, CONTAINER_IMAGE, HOMEPAGE, DOCUMENTATION].freeze
+      end
+
+      # Dependency types for agent metadata.
+      module DependencyType
+        # Depends on another agent
+        AGENT = "agent"
+        # Depends on a tool
+        TOOL = "tool"
+        # Depends on a model
+        MODEL = "model"
+
+        # All valid dependency types
+        ALL = [AGENT, TOOL, MODEL].freeze
+      end
+
+      # Content encoding types.
+      module ContentEncoding
+        # Plain text (no encoding)
+        PLAIN = "plain"
+        # Base64 encoded
+        BASE64 = "base64"
+
+        # All valid encodings
+        ALL = [PLAIN, BASE64].freeze
+      end
+
+      # Event types for SSE streaming.
+      module EventType
+        # New message created
+        MESSAGE_CREATED = "message.created"
+        # Message part received
+        MESSAGE_PART = "message.part"
+        # Message completed
+        MESSAGE_COMPLETED = "message.completed"
+        # Run created
+        RUN_CREATED = "run.created"
+        # Run started executing
+        RUN_IN_PROGRESS = "run.in-progress"
+        # Run awaiting client input
+        RUN_AWAITING = "run.awaiting"
+        # Run completed successfully
+        RUN_COMPLETED = "run.completed"
+        # Run was cancelled
+        RUN_CANCELLED = "run.cancelled"
+        # Run failed
+        RUN_FAILED = "run.failed"
+        # Generic event
+        GENERIC = "generic"
+        # Error event
+        ERROR = "error"
+
+        # All valid event types
+        ALL = [
+          MESSAGE_CREATED, MESSAGE_PART, MESSAGE_COMPLETED,
+          RUN_CREATED, RUN_IN_PROGRESS, RUN_AWAITING,
+          RUN_COMPLETED, RUN_CANCELLED, RUN_FAILED,
+          GENERIC, ERROR
+        ].freeze
+      end
+
+      # Message role types.
+      module Role
+        # Message from user
+        USER = "user"
+        # Message from agent
+        AGENT = "agent"
+
+        # Check if a role is valid.
+        #
+        # @param role [String] role to check
+        # @return [Boolean] true if "user", "agent", or "agent/name"
+        def self.valid?(role)
+          role == USER || role == AGENT || role.to_s.start_with?("agent/")
+        end
+      end
+
+      class << self
+        # Validate an agent name.
+        #
+        # @param name [String, nil] name to validate
+        # @return [Boolean] true if valid RFC 1123 DNS label
+        def valid_agent_name?(name)
+          return false if name.nil? || name.empty?
+          return false if name.length > AGENT_NAME_MAX_LENGTH
+
+          AGENT_NAME_PATTERN.match?(name)
+        end
+
+        # Validate a UUID.
+        #
+        # @param value [String, nil] value to validate
+        # @return [Boolean] true if valid UUID format
+        def valid_uuid?(value)
+          return false if value.nil?
+
+          /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i.match?(value.to_s)
+        end
+
+        # Validate a URL.
+        #
+        # @param value [String, nil] value to validate
+        # @return [Boolean] true if valid HTTP/HTTPS URL
+        def valid_url?(value)
+          return false if value.nil?
+
+          uri = URI.parse(value.to_s)
+          uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+        rescue URI::InvalidURIError
+          false
+        end
+
+        # Generate a new UUID.
+        #
+        # @return [String] UUID string
+        def generate_uuid
+          SecureRandom.uuid
+        end
+      end
+    end
+  end
+end