ask-agent 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a1f33fb0145ac0a1abf50990d15a6f4aa288a67fe8ec11f478cead3b9401a43
-  data.tar.gz: ebaa94902c33f6fe351b97108c6db085096a92ca4206706c8197cba5aaa5d8d5
+  metadata.gz: 0f2eeb2cf5c59ddd76d509d628a809ebe903d9881f5dca8617f511331baaecf7
+  data.tar.gz: 25d07e7d421013bef9ba175011461cbdab6d8370d81e54e8fc742429bbe5473d
 SHA512:
-  metadata.gz: 3a32c8330c3d443980a48df17507cdb4cfa56e67129f7e0fbabce12d9911705a621b85b60f7849ccd422496f46f2c3cc3e4f639cef11673f6530fbc5bd46480e
-  data.tar.gz: 2fd18590c038a8c1221c6422980aebff1edd38e634d53036cb231cae0eda36d15a9df8bcbb48cda146dd828670ebdbf10d9c88bc388b89e0f6fe65c8d7c3788e
+  metadata.gz: 36eab4ddb395657b6bac444f4347cdf783d130e4370c300da944c9636e87ac6ee310b3af98029e2aaffa318d7632a6ae5a89c7168e4a7ae8b247f4b640ba40da
+  data.tar.gz: f2926d63179b15cc08706c4e5b29a4b5f5a8cf32015ad4d62e266eaff6049951d7afe238eb7b2340038dcee0c14f602ad37b9651b801b2c9a775997055df3851

data/CHANGELOG.md

@@ -1,3 +1,37 @@
+## [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/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.0"
   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.0
 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