ask-agent 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a1f33fb0145ac0a1abf50990d15a6f4aa288a67fe8ec11f478cead3b9401a43
-  data.tar.gz: ebaa94902c33f6fe351b97108c6db085096a92ca4206706c8197cba5aaa5d8d5
+  metadata.gz: 55ad6219a4374a7aeb4688533bcf7a0a68ebb166de2d96d2e9953eb6814fe5c5
+  data.tar.gz: 89e4e0413d96f90dd30d4203fa4023331663b2818a5df89c0a60a6975fb8bcb9
 SHA512:
-  metadata.gz: 3a32c8330c3d443980a48df17507cdb4cfa56e67129f7e0fbabce12d9911705a621b85b60f7849ccd422496f46f2c3cc3e4f639cef11673f6530fbc5bd46480e
-  data.tar.gz: 2fd18590c038a8c1221c6422980aebff1edd38e634d53036cb231cae0eda36d15a9df8bcbb48cda146dd828670ebdbf10d9c88bc388b89e0f6fe65c8d7c3788e
+  metadata.gz: 9557223b85bc04778cd6821a9b7807818e06ac85124d95f79469db613a7a23d8e8317db5e6454517adf5b67fd68806eafc4ec145f8c3ea08d01de93d4f939a91
+  data.tar.gz: 53d3a056d6c8004bdd32536f3781bae6a0bee21bd12f1af12bc3eefab02e3f229df6109c8f5f2c6802229177aa28c27a17804bb348e93c4898adce62289222d5

data/CHANGELOG.md

@@ -1,3 +1,45 @@
+## [0.6.1] — 2026-07-21
+
+### Changed
+
+- **`Persistence::Base` now wraps `Ask::State::Adapter`** (from ask-core 0.3.0). Session persistence is backed by the unified state interface instead of a standalone abstract class. `Persistence::InMemory` delegates to `Ask::State::Memory`. The public API is unchanged — `save`, `load`, `delete`, and `list` work identically.
+- **`Persistence::Base.new` accepts `state_adapter:` keyword** for custom backends. Defaults to `Ask::State::Memory` (same behavior as before).
+- **`Persistence::Base#list`** now returns a deduplicated list ordered by most-recently-saved.
+
+## [0.6.0] — 2026-07-21
+
+### Added
+
+- **Agent Scheduler** — `Ask::Agent::Scheduler` runs recurring agent tasks on cron schedules or human-readable intervals. Configure tasks alongside middleware and transforms, then start the background loop.
+
+  ```ruby
+  Ask::Agent.configure do |c|
+    c.scheduler.every "5 minutes", name: "health-check" do
+      Ask::Agent::Session.new(model: "gpt-4o").run("Check server health")
+    end
+
+    c.scheduler.cron "0 9 * * 1-5", name: "morning-report" do
+      Ask::Agent::Session.new(model: "gpt-4o").run("Generate daily report")
+    end
+  end
+
+  Ask::Agent::Scheduler.start   # background thread loop
+  Ask::Agent::Scheduler.stop    # graceful shutdown
+  ```
+
+  Manage the scheduler at runtime:
+  - `Ask::Agent::Scheduler.running?` — check if the loop is active
+  - `Ask::Agent::Scheduler.jobs` — list all scheduled jobs (returns `Rufus::Scheduler::Job` objects with `.name`, `.next_time`, etc.)
+  - `Ask::Agent::Scheduler.job_by_name("health-check")` — find a specific job
+  - Tasks without blocks are valid — they register but execute nothing
+
+  Powered by `rufus-scheduler` (added as a runtime dependency). The scheduler is optional — users who don't configure any tasks are unaffected.
+
+### Changed
+
+- **`Ask::Agent::Configuration`** now exposes `#scheduler` returning a `SchedulerConfig` DSL proxy. No breaking changes for existing users.
+- **Gemspec** — added `rufus-scheduler ~> 3.9` as a runtime dependency.
+
 ## [0.5.0] — 2026-07-21
 
 ### Added

data/lib/ask/agent/configuration.rb

@@ -22,6 +22,12 @@ module Ask
 
         @middleware = Middleware::Pipeline.new
         @stream_transforms = StreamTransforms::Pipeline.new
+        @scheduler_config = SchedulerConfig.new(self)
+      end
+
+      # @return [SchedulerConfig] DSL for defining recurring agent tasks
+      def scheduler
+        @scheduler_config
       end
     end
   end

data/lib/ask/agent/persistence/base.rb

@@ -3,21 +3,67 @@
 module Ask
   module Agent
     module Persistence
+      # Session persistence backed by a generic {Ask::State::Adapter}.
+      #
+      # This wraps session data under namespaced keys so multiple sessions
+      # can coexist in the same state backend alongside other data.
+      #
+      # @example With the default in-memory store
+      #   store = Persistence::InMemory.new
+      #   store.save("session-1", { messages: [...] })
+      #   store.load("session-1")
+      #
+      # @example With a custom state adapter (e.g. Redis)
+      #   store = Persistence::Base.new(
+      #     state_adapter: MyRedisAdapter.new
+      #   )
+      #   store.save("session-1", data)
       class Base
+        KEY_PREFIX = "ask:session:"
+        INDEX_KEY = "ask:session:index"
+
+        # @param state_adapter [Ask::State::Adapter] backend store (defaults to Memory)
+        def initialize(state_adapter: nil)
+          @state = state_adapter || Ask::State::Memory.new
+        end
+
+        # @return [Ask::State::Adapter] the underlying state adapter
+        attr_reader :state
+
+        # Persist a session.
+        # @param session_id [String] the session identifier
+        # @param data [Hash] the session data
         def save(session_id, data)
-          raise NotImplementedError
+          @state.set(key(session_id), data)
+          # Keep the index list unique — remove existing entry first then append
+          @state.list_remove(INDEX_KEY, session_id)
+          @state.list_append(INDEX_KEY, session_id)
         end
 
+        # Load a session.
+        # @param session_id [String] the session identifier
+        # @return [Hash, nil] the session data, or nil if not found
         def load(session_id)
-          raise NotImplementedError
+          @state.get(key(session_id))
         end
 
+        # Delete a session.
+        # @param session_id [String] the session identifier
         def delete(session_id)
-          raise NotImplementedError
+          @state.delete(key(session_id))
+          @state.list_remove(INDEX_KEY, session_id)
         end
 
+        # List all stored session IDs.
+        # @return [Array<String>] list of session IDs
         def list
-          raise NotImplementedError
+          @state.list_range(INDEX_KEY, 0, -1)
+        end
+
+        private
+
+        def key(session_id)
+          "#{KEY_PREFIX}#{session_id}"
         end
       end
     end

data/lib/ask/agent/persistence/in_memory.rb

@@ -3,26 +3,11 @@
 module Ask
   module Agent
     module Persistence
+      # In-memory session persistence. Backed by {Ask::State::Memory}.
+      # Data is lost when the process exits.
       class InMemory < Base
         def initialize
-          @store = {}
-          @mutex = Mutex.new
-        end
-
-        def save(session_id, data)
-          @mutex.synchronize { @store[session_id] = data }
-        end
-
-        def load(session_id)
-          @mutex.synchronize { @store[session_id] }
-        end
-
-        def delete(session_id)
-          @mutex.synchronize { @store.delete(session_id) }
-        end
-
-        def list
-          @mutex.synchronize { @store.keys }
+          super(state_adapter: Ask::State::Memory.new)
         end
       end
     end

data/lib/ask/agent/scheduler.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    # Schedules recurring agent runs.
+    #
+    # Configure tasks through {Ask::Agent::Configuration#scheduler}, then
+    # start the scheduler loop. Tasks run in background threads managed by
+    # +rufus-scheduler+.
+    #
+    # @example
+    #   Ask::Agent.configure do |c|
+    #     c.scheduler.every "5 minutes", name: "health-check" do
+    #       Ask::Agent::Session.new(model: "gpt-4o").run("Check server health")
+    #     end
+    #
+    #     c.scheduler.cron "0 9 * * 1-5", name: "morning-report" do
+    #       Ask::Agent::Session.new(model: "gpt-4o").run("Generate daily report")
+    #     end
+    #   end
+    #
+    #   Ask::Agent::Scheduler.start   # background thread loop
+    #   Ask::Agent::Scheduler.running? # => true
+    #   Ask::Agent::Scheduler.jobs     # => list of rufus jobs
+    #   Ask::Agent::Scheduler.stop    # graceful shutdown
+    class Scheduler
+      @instance = nil
+      @mutex = Mutex.new
+
+      class << self
+        # @return [Scheduler] the singleton instance
+        def instance
+          @instance ||= new
+        end
+
+        # Start the scheduler background thread.
+        # All configured tasks begin running on their schedules.
+        # @return [Scheduler] the singleton instance
+        def start
+          @mutex.synchronize do
+            return instance if instance.up?
+
+            instance.start
+          end
+          instance
+        end
+
+        # Gracefully stop the scheduler and wait for running tasks.
+        def stop
+          @mutex.synchronize do
+            instance.stop
+            @instance = nil
+          end
+        end
+
+        # @return [Boolean] whether the scheduler loop is active
+        def running?
+          instance.up?
+        end
+
+        # @return [Array<Rufus::Scheduler::Job>] currently scheduled jobs
+        def jobs
+          instance.jobs
+        end
+
+        # Find a scheduled job by its name.
+        # @param name [String] the job name
+        # @return [Rufus::Scheduler::Job, nil]
+        def job_by_name(name)
+          jobs.find { |j| j.name == name }
+        end
+      end
+
+      def initialize
+        @rufus = nil
+        @own_mutex = Mutex.new
+      end
+
+      # Start the rufus-scheduler loop and register all configured tasks.
+      # @return [self]
+      def start
+        @own_mutex.synchronize do
+          return self if @rufus&.up?
+
+          require "rufus-scheduler"
+
+          @rufus = Rufus::Scheduler.new
+
+          config = Ask::Agent.configuration
+
+          # Register tasks that were configured statically
+          config.scheduler.each_task do |task|
+            schedule_task(task)
+          end
+        end
+        self
+      end
+
+      # Stop the scheduler and wait for running jobs to finish.
+      def stop
+        @own_mutex.synchronize do
+          @rufus&.shutdown(:wait)
+          @rufus = nil
+        end
+      end
+
+      # @return [Boolean] true if the rufus scheduler is active
+      def up?
+        @rufus&.up? || false
+      end
+
+      # @return [Array<Rufus::Scheduler::Job>] currently scheduled jobs
+      def jobs
+        @rufus&.jobs || []
+      end
+
+      private
+
+      def schedule_task(task)
+        block = task[:block]
+        name = task[:name]
+
+        case task[:type]
+        when :every
+          @rufus.every task[:interval], name: name do
+            block&.call
+          end
+        when :cron
+          @rufus.cron task[:cron], name: name do
+            block&.call
+          end
+        else
+          raise ArgumentError, "Unknown schedule type: #{task[:type].inspect}"
+        end
+      end
+    end
+
+    # DSL proxy used inside {Ask::Agent::Configuration#scheduler}.
+    # Collects task definitions that the {Scheduler} registers on start.
+    class SchedulerConfig
+      def initialize(config)
+        @config = config
+        @tasks = []
+      end
+
+      # Schedule a block to run on a recurring interval.
+      #
+      # @param interval [String] human-readable interval (e.g. "5 minutes", "1 hour")
+      # @param name [String, nil] optional job name for identification
+      # @yield block to execute on each tick
+      def every(interval, name: nil, &block)
+        @tasks << { type: :every, interval: interval, name: name, block: block }
+        self
+      end
+
+      # Schedule a block to run on a cron schedule.
+      #
+      # @param cron_expression [String] standard cron syntax (e.g. "0 9 * * 1-5")
+      # @param name [String, nil] optional job name for identification
+      # @yield block to execute at each scheduled time
+      def cron(cron_expression, name: nil, &block)
+        @tasks << { type: :cron, cron: cron_expression, name: name, block: block }
+        self
+      end
+
+      # Yield each configured task definition.
+      def each_task(&block)
+        @tasks.each(&block)
+      end
+    end
+  end
+end

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.5.0"
+    VERSION = "0.6.1"
   end
 end

data/lib/ask/agent.rb

@@ -70,6 +70,7 @@ require_relative "agent/compactor"
 require_relative "agent/hooks"
 require_relative "agent/configuration"
 require_relative "agent/meta_agent"
+require_relative "agent/scheduler"
 require_relative "agent/persistence/base"
 require_relative "agent/persistence/in_memory"
 require_relative "agent/skills/load_skill_tool"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Kaka Ruto
@@ -79,6 +79,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rufus-scheduler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -152,6 +166,7 @@ files:
 - lib/ask/agent/persistence/base.rb
 - lib/ask/agent/persistence/in_memory.rb
 - lib/ask/agent/reflector.rb
+- lib/ask/agent/scheduler.rb
 - lib/ask/agent/session.rb
 - lib/ask/agent/skills/load_skill_tool.rb
 - lib/ask/agent/stream_transforms/base.rb