simple_acp 0.0.1

data/lib/simple_acp/server/context.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module SimpleAcp
+  module Server
+    # Request context passed to agent handlers during execution.
+    #
+    # Provides access to input messages, session state, conversation history,
+    # and methods for controlling execution flow.
+    #
+    # @example Accessing input
+    #   server.agent("echo") do |context|
+    #     text = context.input.first.text_content
+    #     Models::Message.agent("You said: #{text}")
+    #   end
+    #
+    # @example Using session state
+    #   server.agent("counter") do |context|
+    #     count = (context.state || 0) + 1
+    #     context.set_state(count)
+    #     Models::Message.agent("Count: #{count}")
+    #   end
+    class Context
+      # @return [Models::Run] the current run being executed
+      attr_reader :run
+
+      # @return [Models::Session, nil] the session (if any)
+      attr_reader :session
+
+      # @return [Array<Models::Message>] input messages for this run
+      attr_reader :input
+
+      # @return [Server::Base] reference to the server
+      attr_reader :server
+
+      # Initialize a new context.
+      #
+      # @param run [Models::Run] the run being executed
+      # @param session [Models::Session, nil] optional session
+      # @param input [Array<Models::Message>] input messages
+      # @param server [Server::Base] the server instance
+      def initialize(run:, session:, input:, server:)
+        @run = run
+        @session = session
+        @input = input
+        @server = server
+        @cancelled = false
+      end
+
+      # @return [String] the name of the agent being executed
+      def agent_name
+        @run.agent_name
+      end
+
+      # @return [String] the unique run ID
+      def run_id
+        @run.run_id
+      end
+
+      # @return [String, nil] the session ID if a session is active
+      def session_id
+        @session&.id
+      end
+
+      # Check if the run has been cancelled.
+      #
+      # @return [Boolean] true if cancelled
+      def cancelled?
+        @cancelled
+      end
+
+      # Mark the run as cancelled.
+      #
+      # @return [void]
+      def cancel!
+        @cancelled = true
+      end
+
+      # Get conversation history from the session.
+      #
+      # @return [Array<Models::Message>] previous messages in the session
+      def history
+        @session&.history || []
+      end
+
+      # Get arbitrary state data from the session.
+      #
+      # @return [Object, nil] the stored state data
+      def state
+        @session&.state
+      end
+
+      # Update the session state with new data.
+      #
+      # @param new_state [Object] the state data to store
+      # @return [void]
+      def set_state(new_state)
+        @session&.set_state(new_state)
+        @server.storage.save_session(@session) if @session
+      end
+
+      # Request additional input from the client, pausing execution.
+      #
+      # This puts the run into an "awaiting" state until the client
+      # calls resume with the requested input.
+      #
+      # @param prompt_message [Models::Message] message to display to the client
+      # @return [RunYieldAwait] yield this from your agent to pause
+      #
+      # @example Multi-turn conversation
+      #   server.agent("questioner") do |context|
+      #     Enumerator.new do |yielder|
+      #       result = context.await_message(Models::Message.agent("What is your name?"))
+      #       yielder << result
+      #       name = context.resume_message&.text_content
+      #       yielder << RunYield.new(Models::Message.agent("Hello, #{name}!"))
+      #     end
+      #   end
+      def await_message(prompt_message)
+        request = Models::MessageAwaitRequest.new(message: prompt_message)
+        @run.await!(request)
+        @server.storage.save_run(@run)
+
+        # Return a result that indicates the run is awaiting
+        RunYieldAwait.new(request: request)
+      end
+
+      # Log a message for debugging or trajectory tracking.
+      #
+      # @param message [String] the message to log
+      # @return [void]
+      def log(message)
+        SimpleAcp.logger&.info("[#{agent_name}] #{message}")
+      end
+
+      # Get the resume message (only available during resume).
+      #
+      # This method returns nil for initial contexts. Override in
+      # ResumeContext to return the actual resume message.
+      #
+      # @return [Models::Message, nil] nil for initial context
+      def resume_message
+        nil
+      end
+    end
+
+    # Wrapper for yielding output messages from an agent.
+    #
+    # Use this when streaming responses from an Enumerator-based agent handler.
+    #
+    # @example
+    #   Enumerator.new do |yielder|
+    #     yielder << RunYield.new(Models::Message.agent("First message"))
+    #     yielder << RunYield.new(Models::Message.agent("Second message"))
+    #   end
+    class RunYield
+      # @return [Models::Message] the message to output
+      attr_reader :message
+
+      # Create a new message yield.
+      #
+      # @param message [Models::Message, Hash] the message to yield
+      def initialize(message)
+        @message = message.is_a?(Models::Message) ? message : Models::Message.from_hash(message)
+      end
+    end
+
+    # Wrapper for pausing execution and awaiting client input.
+    #
+    # Yield this from an agent to pause execution until the client
+    # resumes with the requested input.
+    class RunYieldAwait
+      # @return [Models::AwaitRequest] the await request details
+      attr_reader :request
+
+      # Create a new await yield.
+      #
+      # @param request [Models::AwaitRequest] the request for client input
+      def initialize(request:)
+        @request = request
+      end
+    end
+
+    # Extended context for resuming an awaited run.
+    #
+    # Contains the client's response to the await request.
+    class ResumeContext < Context
+      # @return [Models::AwaitResume] the client's resume payload
+      attr_reader :await_resume
+
+      # Initialize a resume context.
+      #
+      # @param run [Models::Run] the run being resumed
+      # @param session [Models::Session, nil] optional session
+      # @param input [Array<Models::Message>] original input messages
+      # @param server [Server::Base] the server instance
+      # @param await_resume [Models::AwaitResume] the client's response
+      def initialize(run:, session:, input:, server:, await_resume:)
+        super(run: run, session: session, input: input, server: server)
+        @await_resume = await_resume
+      end
+
+      # Get the message from the client's resume payload.
+      #
+      # @return [Models::Message, nil] the client's response message
+      def resume_message
+        @await_resume&.message
+      end
+    end
+  end
+end

data/lib/simple_acp/server/falcon_runner.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "async"
+require "falcon"
+require "falcon/server"
+require "protocol/rack"
+require "io/endpoint"
+require "io/endpoint/address_endpoint"
+
+module SimpleAcp
+  module Server
+    # Falcon-based server runner using fiber concurrency.
+    #
+    # Provides efficient handling of SSE streams and long-lived
+    # connections through Async's fiber scheduler.
+    #
+    # @example Starting a server
+    #   app = server.to_app
+    #   FalconRunner.run(app, port: 8000)
+    module FalconRunner
+      # Start the server using Falcon.
+      #
+      # @param app [#call] the Rack application
+      # @param port [Integer] port to bind to (default: 8000)
+      # @param host [String] host to bind to (default: "0.0.0.0")
+      # @param options [Hash] additional options
+      # @option options [Integer] :count number of worker processes
+      # @return [void]
+      def self.run(app, port: 8000, host: "0.0.0.0", **options)
+        endpoint = IO::Endpoint::AddressEndpoint.new(Addrinfo.tcp(host, port))
+
+        puts "ACP Server (Falcon) running on http://#{host}:#{port}"
+
+        server_task = nil
+
+        # Handle interrupt for graceful shutdown
+        trap("INT") do
+          puts "\nShutting down..."
+          Thread.main.raise(Interrupt)
+        end
+
+        trap("TERM") do
+          puts "\nShutting down..."
+          Thread.main.raise(Interrupt)
+        end
+
+        begin
+          Sync do |task|
+            rack_app = Protocol::Rack::Adapter.new(app)
+            server = Falcon::Server.new(rack_app, endpoint, protocol: Async::HTTP::Protocol::HTTP1, scheme: "http")
+
+            server_task = server.run
+            server_task.wait
+          end
+        rescue Interrupt
+          # Graceful shutdown
+        end
+      end
+    end
+  end
+end

data/lib/simple_acp/storage/base.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module SimpleAcp
+  module Storage
+    # Abstract base class for storage backends.
+    #
+    # Defines the interface for storing runs, sessions, and events.
+    # Implementations include Memory, Redis, and PostgreSQL.
+    #
+    # @abstract Subclass and implement all methods
+    #
+    # @example Custom storage backend
+    #   class MyStorage < SimpleAcp::Storage::Base
+    #     def get_run(run_id)
+    #       # ...
+    #     end
+    #     # ... implement other methods
+    #   end
+    class Base
+      # Initialize the storage backend.
+      #
+      # @param options [Hash] backend-specific options
+      def initialize(options = {})
+        @options = options
+      end
+
+      # Retrieve a run by ID.
+      #
+      # @param run_id [String] the run ID
+      # @return [Models::Run, nil] the run or nil if not found
+      # @raise [NotImplementedError] if not implemented
+      def get_run(run_id)
+        raise NotImplementedError, "#{self.class}#get_run must be implemented"
+      end
+
+      # Save a run.
+      #
+      # @param run [Models::Run] the run to save
+      # @return [Models::Run] the saved run
+      # @raise [NotImplementedError] if not implemented
+      def save_run(run)
+        raise NotImplementedError, "#{self.class}#save_run must be implemented"
+      end
+
+      # Delete a run.
+      #
+      # @param run_id [String] the run ID to delete
+      # @return [void]
+      # @raise [NotImplementedError] if not implemented
+      def delete_run(run_id)
+        raise NotImplementedError, "#{self.class}#delete_run must be implemented"
+      end
+
+      # List runs with optional filtering.
+      #
+      # @param agent_name [String, nil] filter by agent name
+      # @param session_id [String, nil] filter by session ID
+      # @param limit [Integer] maximum number to return (default: 10)
+      # @param offset [Integer] number to skip (default: 0)
+      # @return [Hash] with :runs and :total keys
+      # @raise [NotImplementedError] if not implemented
+      def list_runs(agent_name: nil, session_id: nil, limit: 10, offset: 0)
+        raise NotImplementedError, "#{self.class}#list_runs must be implemented"
+      end
+
+      # Retrieve a session by ID.
+      #
+      # @param session_id [String] the session ID
+      # @return [Models::Session, nil] the session or nil if not found
+      # @raise [NotImplementedError] if not implemented
+      def get_session(session_id)
+        raise NotImplementedError, "#{self.class}#get_session must be implemented"
+      end
+
+      # Save a session.
+      #
+      # @param session [Models::Session] the session to save
+      # @return [Models::Session] the saved session
+      # @raise [NotImplementedError] if not implemented
+      def save_session(session)
+        raise NotImplementedError, "#{self.class}#save_session must be implemented"
+      end
+
+      # Delete a session.
+      #
+      # @param session_id [String] the session ID to delete
+      # @return [void]
+      # @raise [NotImplementedError] if not implemented
+      def delete_session(session_id)
+        raise NotImplementedError, "#{self.class}#delete_session must be implemented"
+      end
+
+      # Add an event to a run.
+      #
+      # @param run_id [String] the run ID
+      # @param event [Models::Event] the event to add
+      # @return [Models::Event] the added event
+      # @raise [NotImplementedError] if not implemented
+      def add_event(run_id, event)
+        raise NotImplementedError, "#{self.class}#add_event must be implemented"
+      end
+
+      # Get events for a run.
+      #
+      # @param run_id [String] the run ID
+      # @param limit [Integer] maximum number to return (default: 100)
+      # @param offset [Integer] number to skip (default: 0)
+      # @return [Array<Models::Event>] list of events
+      # @raise [NotImplementedError] if not implemented
+      def get_events(run_id, limit: 100, offset: 0)
+        raise NotImplementedError, "#{self.class}#get_events must be implemented"
+      end
+
+      # Close the storage connection.
+      #
+      # @return [void]
+      def close
+        # Override in subclasses if needed
+      end
+
+      # Check if the storage is accessible.
+      #
+      # @return [Boolean] true if accessible
+      def ping
+        true
+      end
+    end
+  end
+end

data/lib/simple_acp/storage/memory.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module SimpleAcp
+  module Storage
+    # Thread-safe in-memory storage backend.
+    #
+    # This is the default storage backend. Data is lost when the process exits.
+    # Uses concurrent-ruby for thread safety.
+    #
+    # @example
+    #   storage = SimpleAcp::Storage::Memory.new
+    #   server = SimpleAcp::Server::Base.new(storage: storage)
+    class Memory < Base
+      def initialize(options = {})
+        super
+        @runs = Concurrent::Map.new
+        @sessions = Concurrent::Map.new
+        @events = Concurrent::Map.new
+        @mutex = Mutex.new
+      end
+
+      # @see Base#get_run
+      def get_run(run_id)
+        @runs[run_id]
+      end
+
+      # @see Base#save_run
+      def save_run(run)
+        @runs[run.run_id] = run
+        run
+      end
+
+      # @see Base#delete_run
+      def delete_run(run_id)
+        @events.delete(run_id)
+        @runs.delete(run_id)
+      end
+
+      # @see Base#list_runs
+      def list_runs(agent_name: nil, session_id: nil, limit: 10, offset: 0)
+        runs = @runs.values
+
+        runs = runs.select { |r| r.agent_name == agent_name } if agent_name
+        runs = runs.select { |r| r.session_id == session_id } if session_id
+
+        runs = runs.sort_by { |r| r.created_at || Time.at(0) }.reverse
+
+        {
+          runs: runs.drop(offset).take(limit),
+          total: runs.length
+        }
+      end
+
+      # @see Base#get_session
+      def get_session(session_id)
+        @sessions[session_id]
+      end
+
+      # @see Base#save_session
+      def save_session(session)
+        @sessions[session.id] = session
+        session
+      end
+
+      # @see Base#delete_session
+      def delete_session(session_id)
+        @sessions.delete(session_id)
+      end
+
+      # @see Base#add_event
+      def add_event(run_id, event)
+        @mutex.synchronize do
+          @events[run_id] ||= []
+          @events[run_id] << event
+        end
+        event
+      end
+
+      # @see Base#get_events
+      def get_events(run_id, limit: 100, offset: 0)
+        events = @events[run_id] || []
+        events.drop(offset).take(limit)
+      end
+
+      # Clear all stored data.
+      #
+      # @return [void]
+      def clear!
+        @runs.clear
+        @sessions.clear
+        @events.clear
+      end
+
+      # Get storage statistics.
+      #
+      # @return [Hash] counts of runs, sessions, and events
+      def stats
+        {
+          runs: @runs.size,
+          sessions: @sessions.size,
+          events: @events.values.sum(&:length)
+        }
+      end
+    end
+  end
+end