insika 0.3.0 → 0.7.0

data/lib/insika/schedule_engine.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # the tick-driven FIRER of recurring schedules: the engine's
+  # fourth duty (after the outbox drain, retention/funnel and the follow-up
+  # firer). One pass per claim window (the followup/funnel idiom); each due
+  #   schedule is claimed transactionally — re-read inside its own transaction,
+  #   so two workers racing a window serialize on the backend lock and exactly
+  #   one fires (the multi-worker at-most-once claim, per row).
+  #
+  # Gating order:
+  #
+  #   declared? (reconciled from the profiles) -> enabled + due -> no-catch-up
+  #   (a window older than one claim window is MISSED, recorded, never
+  #   replayed) -> overlap (the last task still live) -> budget (a hard
+  #   window at/over cap) -> FIRE.
+  #
+  # Skips are DATA, never silent: `last_skip { at, reason }` on the row, for
+  # the Studio. The engine never queues — a skipped window advances the
+  # schedule's lattice. The turn it creates is delivered by the existing
+  # pipeline (it holds no channel code, like the FollowupEngine).
+  class ScheduleEngine
+    SCOPE = "schedule_fire"
+    KEY = "claim"
+    DEFAULT_WINDOW = 300 # seconds; one firing worker per window
+    TENANT = "platform"  # the single-tenant default (ledger rules) — see `tenant_for`
+
+    ACTIVE_STATUSES = %i[queued running waiting paused].freeze
+
+    # The tenant a SCHEDULED turn declares. Every other turn gets its tenant
+    # from its CALLER (an authenticated tenant token, a Command built with
+    # `tenant:`) — a scheduled turn has no caller, so it is the agent's OWN
+    # declaration instead: `metadata["tenant"]`, the same "stable per agent,
+    # from the pack" home `store_id` already lives in (never the model, never
+    # a policy — just a fact the pack states). Absent -> the single-tenant
+    # default, unchanged for every profile that does not declare one.
+    #
+    # PUBLIC and STATELESS on purpose: the Studio's own schedule list
+    # (`studio/app.rb`) must resolve to the exact SAME tenant the fire path
+    # uses, or a declared schedule becomes invisible there — one formula, two
+    # callers, never a second copy to drift.
+    def self.tenant_for(profile)
+      meta = profile.respond_to?(:metadata) ? profile.metadata : nil
+      Insika::Coercion.presence(meta && meta["tenant"]) || TENANT
+    end
+
+    def initialize(store:, schedule_store:, task_store:, session_store:,
+                   profiles:, executor:, budget_ledger: nil, event_stream: nil,
+                   window: DEFAULT_WINDOW, now: nil)
+      @store = store
+      @schedule_store = schedule_store
+      @task_store = task_store
+      @session_store = session_store
+      @profiles = profiles
+      @executor = executor
+      @budget_ledger = budget_ledger
+      @event_stream = event_stream
+      @window = window
+      @now = now
+    end
+
+    # -> { claimed: false }
+    #  | { claimed: true, fired: N, skipped: N, errors: N,
+    #      skip_reasons: { "reason" => N } }
+    # A StoreError on ONE schedule aborts THAT schedule's transaction
+    # (rescued, counted, the loop continues) — a broken row must not hold the
+    # other schedules' runs hostage.
+    def run
+      now_time = @now || Time.now.utc
+      return { claimed: false } unless claim_window(now_time)
+
+      sync_from_profiles(now_time)
+
+      fired = 0
+      skipped = 0
+      errors = 0
+      reasons = Hash.new(0)
+
+      @schedule_store.due(now: now_time).each do |record|
+        begin
+          outcome = fire_record(record, now_time)
+          case outcome
+          when :fired then fired += 1
+          when Array
+            # a skip is recorded on the row (never silent) and counted here.
+            skipped += 1
+            reasons[outcome[1].to_s] += 1
+          end
+        rescue StandardError
+          # a broken schedule must not hold the other schedules' runs
+          # hostage — its own transaction already rolled back.
+          errors += 1
+        end
+      end
+
+      { claimed: true, fired: fired, skipped: skipped, errors: errors,
+        skip_reasons: reasons }
+    end
+
+    private
+
+    # Reconciliation: the PROFILES are the source of the declarations (DSL /
+    # API / Studio); the store rows are the derived view the fire path reads.
+    # One pass: drop rows whose agent no longer exists, then upsert each
+    # profile's declared schedules (and drop each agent's undeclared rows).
+    def sync_from_profiles(now_time)
+      ids = @profiles.ids.map(&:to_s)
+      @store.transaction do
+        @schedule_store.all.each do |row|
+          @schedule_store.delete(tenant: row.tenant, agent: row.agent, id: row.id) unless ids.include?(row.agent)
+        end
+        @profiles.all.each do |profile|
+          schedules = profile.respond_to?(:schedules) ? profile.schedules : nil
+          @schedule_store.sync_declared(tenant: self.class.tenant_for(profile), agent: profile.id,
+                                        schedules: schedules, now: now_time)
+        end
+      end
+    end
+
+    # -> :fired | [:skipped, reason] — claimed per row, inside ONE
+    # transaction: the re-read, the gates, the task creation and the lattice
+    # advance commit together or not at all — and the SPAWN happens AFTER the
+    # commit, so a spawn failure never unwinds the fire (the durable :queued
+    # task is the recovery sweep's to handle). `next`, never `return`, inside
+    # the block (a non-local return skips the backend's COMMIT).
+    def fire_record(record, now_time)
+      task = nil
+      outcome = nil
+      spawn_profile = nil
+      @store.transaction do
+        current = @schedule_store.find(tenant: record.tenant, agent: record.agent, id: record.id)
+        # a racing worker already advanced/deleted the row — nothing for this pass.
+        unless current
+          outcome = [:skipped, :stale]
+          next
+        end
+        unless current.enabled
+          outcome = [:skipped, :stale]
+          next
+        end
+        next_at = Time.iso8601(current.next_fire_at.to_s)
+        unless next_at <= now_time
+          outcome = [:skipped, :stale] # the racing worker claimed the window
+          next
+        end
+
+        # the no-catch-up policy: a window older than ONE claim window is
+        # MISSED, not replayed — the lattice advances and the row records it.
+        if next_at < now_time - @window
+          @schedule_store.mark_skip(id: current.id, tenant: current.tenant,
+                                    agent: current.agent, reason: :late,
+                                    next_fire_at: next_after(current, now_time),
+                                    now: now_time)
+          outcome = [:skipped, :late]
+          next
+        end
+
+        # overlap: the previous run is still live — skip + record, never a queue.
+        if overlap?(current)
+          @schedule_store.mark_skip(id: current.id, tenant: current.tenant,
+                                    agent: current.agent, reason: :overlap,
+                                    next_fire_at: next_after(current, now_time),
+                                    now: now_time)
+          outcome = [:skipped, :overlap]
+          next
+        end
+
+        profile = @profiles.fetch(current.agent)
+        if profile && budget_exhausted?(profile, current, now_time)
+          @schedule_store.mark_skip(id: current.id, tenant: current.tenant,
+                                    agent: current.agent, reason: :budget,
+                                    next_fire_at: next_after(current, now_time),
+                                    now: now_time)
+          outcome = [:skipped, :budget]
+          next
+        end
+
+        task = commit_run(current, profile, now_time)
+        spawn_profile = derived_profile(current, profile)
+        outcome = :fired
+      end
+      return outcome || [:skipped, :stale] unless task
+
+      # AFTER the commit: the spawn. A failure propagates to the pass (counted
+      # as an error) — the fire already committed, and the :queued task is
+      # recovered by the tick's sweep.
+      @executor.spawn_in_session(task, profile: spawn_profile)
+      emit_fired(record, task.id)
+      :fired
+    end
+
+    # The atomic claim inside the pass's transaction: the task and the
+    # schedule's state (last run, task id, next fire) commit together or not
+    # at all (the follow-up firer's D5 shape).
+    def commit_run(current, profile, now_time)
+      session_id = resolve_session(current)
+      command = {
+        "type" => "scheduled_run",
+        "session_id" => session_id,
+        "payload" => {
+          "agent" => current.agent, "session_id" => session_id,
+          "message" => current.message, "origin" => Insika::MessageOrigin::SCHEDULED,
+          "schedule_id" => current.id
+        },
+        "meta" => { "tenant" => current.tenant, "transport" => "schedule" }
+      }
+      task = @task_store.create(command: command, session_id: session_id)
+      @schedule_store.transition_fire(id: current.id, tenant: current.tenant,
+                                      agent: current.agent, task_id: task.id,
+                                      next_fire_at: next_after(current, now_time),
+                                      now: now_time)
+      task
+    end
+
+    # -> session_id for the run. session_mode "new" = a fresh session per run
+    # (the report case); "fixed" = the declared session, created on first run
+    # (the "standing assistant" case).
+    def resolve_session(current)
+      if current.session_mode == "fixed"
+        sid = current.session_id.to_s
+        sid = "sched-#{current.agent}-#{current.id}" if sid.empty?
+        @session_store.create(id: sid) unless @session_store.find(sid)
+        sid
+      else
+        @session_store.create.id
+      end
+    end
+
+    # The profile the turn runs on: the base profile with the schedule's
+    # overrides merged (per-schedule ceiling, never a store-wide change). The
+    # base is untouched — a second schedule cannot see a sibling's overrides.
+    def derived_profile(current, base)
+      overrides = current.overrides
+      return base if overrides.nil? || overrides.empty?
+
+      limits = base.limits.dup
+      limits[:turn_timeout] = overrides["turn_timeout"] if overrides["turn_timeout"]
+      limits[:max_tool_calls] = overrides["max_tool_calls"] if overrides["max_tool_calls"]
+      Insika::AgentProfile.build(**base.to_h.merge(limits: limits,
+                                                   model: overrides["model"] || base.model))
+    end
+
+    # The next lattice point after `now`: for `every`, the next interval
+    # boundary; for cron, the next expression occurrence in the schedule's tz.
+    # nil (a cron that can never fire) makes the row never due again.
+    def next_after(current, now_time)
+      if current.every
+        base = Time.iso8601(current.next_fire_at.to_s)
+        base + ((now_time - base).to_i / current.every + 1) * current.every
+      else
+        Insika::Cron.new(current.cron).next_after(now_time, tz: current.tz)
+      end
+    end
+
+    def overlap?(current)
+      task_id = current.last_task_id.to_s
+      return false if task_id.empty?
+
+      task = @task_store.find(task_id)
+      task && ACTIVE_STATUSES.include?(task.status)
+    end
+
+    # A HARD budget at/over a window cap = skip (the edge would fail the turn
+    # anyway — this refuses to even queue it). A soft budget crosses and runs;
+    # the ledger warns as usual. Mirror of EdgeLimiter#budget_windows — the
+    # SOFT half is the edge's, this is the schedule gate's.
+    def budget_exhausted?(profile, current, now_time)
+      budget = profile.respond_to?(:budget) ? profile.budget : nil
+      return false if budget.nil? || @budget_ledger.nil?
+
+      soft = budget["soft"] == true
+      %i[daily monthly].any? do |window|
+        cap = budget[window.to_s].to_i
+        next false unless cap.positive?
+
+        spent = @budget_ledger.current(tenant: current.tenant, agent: current.agent,
+                                       now: now_time)[window]
+        !soft && spent >= cap
+      end
+    end
+
+    def emit_fired(record, task_id)
+      return unless @event_stream
+
+      @event_stream.emit(Insika::Event.new(
+                           type: :schedule_fired,
+                           data: { id: record.id, agent: record.agent, task_id: task_id },
+                           meta: { tenant: record.tenant, at: Time.now.utc.iso8601 }
+                         ))
+    end
+
+    # The claim window (the funnel_fold.rb idiom — read-check-write on one key
+    # inside a transaction): the O(n) scans never ride the 60 s tick, and two
+    # workers racing a pass serialize on the backend's lock.
+    def claim_window(now_time)
+      @store.transaction do
+        current = @store.get(SCOPE, KEY)
+        last = current && begin
+          Time.iso8601(current["claimed_at"].to_s)
+        rescue ArgumentError
+          nil # a corrupted claim is not a claim — take the window
+        end
+        if last.nil? || (now_time - last) >= @window
+          @store.set(SCOPE, KEY, { "claimed_at" => now_time.iso8601 })
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/insika/schedule_store.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Insika
+  # the per-agent schedule rows of the recurring feature — one
+  # row per declared schedule, keyed `tenant:agent:id`, holding BOTH the
+  # declaration (a copy of the profile's `schedules` entry — the engine reads
+  # the store, never the profile, on the fire path) and the runtime state
+  # (`next_fire_at`, `last_run_at`, `last_task_id`, `last_skip`).
+  #
+  # The row is a DERIVED record: the profile declaration is the config (the
+  # DSL, the API, the Studio all edit the profile); the ScheduleEngine
+  # reconciles rows with declarations at each pass. The engine OWNS the
+  # runtime writes — `transition_fire`/`mark_skip` are called only inside the
+  # engine's transaction (the D5 discipline), never by a consumer. A row that
+  # is no longer declared is deleted (no zombie schedules); a row whose
+  # declaration is malformed is deleted too — a broken schedule must not keep
+  # firing with stale text (the doctor names it).
+  #
+  # Multi-worker at-most-once rides Store#transaction: the pass re-reads the
+  # row inside the transaction, so two workers serialize on the backend lock
+  # and only one advances `next_fire_at`.
+  class ScheduleStore
+    SCOPE = "schedules"
+
+    Record = Data.define(:id, :tenant, :agent, :every, :cron, :tz, :message,
+                         :session_mode, :session_id, :overrides, :enabled,
+                         :next_fire_at, :last_run_at, :last_task_id, :last_skip,
+                         :created_at, :updated_at)
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # Reconcile: upsert the declaration's row, or delete it when the
+    # declaration is gone/malformed. Called by the engine inside its pass
+    # transaction. A NEW or CHANGED declaration recomputes `next_fire_at`
+    # (the trigger lattice starts fresh); an unchanged row keeps its.
+    def sync_declared(tenant:, agent:, schedules: nil, now: Time.now.utc)
+      kept = []
+      Array(schedules).each do |declaration|
+        schedule = Insika::Schedule.parse(declaration)
+        next if schedule.nil? # malformed — dropped, the doctor names it
+
+        keep = upsert(tenant: tenant, agent: agent, schedule: schedule, now: now)
+        kept << schedule.id if keep
+      end
+
+      # drop rows the agent no longer declares
+      prefix = "#{tenant_id(tenant)}:#{agent}:"
+      @store.list(SCOPE).each do |k|
+        next unless k.start_with?(prefix)
+        next if kept.include?(k.split(":").last)
+
+        @store.delete(SCOPE, k)
+      end
+      kept
+    end
+
+    # -> Record | nil
+    def find(tenant:, agent:, id:)
+      record = @store.get(SCOPE, key(tenant, agent, id))
+      record && to_record(record)
+    end
+
+    # -> [Record] — one agent's rows (the Studio's read), lexicographic.
+    def for_agent(tenant:, agent:)
+      prefix = "#{tenant_id(tenant)}:#{agent}:"
+      @store.list(SCOPE).filter_map do |k|
+        next unless k.start_with?(prefix)
+
+        to_record(@store.get(SCOPE, k))
+      end
+    end
+
+    # -> [Record] — every row (the Studio grid, the engine pass).
+    def all
+      @store.list(SCOPE).filter_map { |k| to_record(@store.get(SCOPE, k)) }
+    end
+
+    # -> [Record] — enabled AND due, oldest first (determinism). A row whose
+    # next_fire_at is nil (a cron that can never fire) is never due.
+    def due(now: Time.now.utc)
+      cutoff = now.iso8601
+      all.select { |r| r.enabled && !r.next_fire_at.to_s.empty? && r.next_fire_at.to_s <= cutoff }
+         .sort_by { |r| [r.next_fire_at.to_s, r.id] }
+    end
+
+    # The engine's atomic fire claim — the LAST step of the fire's
+    # transaction: advance the lattice, stamp the run, clear the skip.
+    # Callers pass `id` and the engine's OWN transaction encloses this.
+    def transition_fire(id:, tenant:, agent:, task_id:, next_fire_at:, now: Time.now.utc)
+      mutate(tenant, agent, id, now) do |record|
+        record["last_run_at"] = now.utc.iso8601
+        record["last_task_id"] = task_id.to_s
+        record["next_fire_at"] = next_fire_at.iso8601
+        record["last_skip"] = nil
+      end
+    end
+
+    # The visible skip — recorded, never silent: `next_fire_at` advances
+    # (the window is skipped, not queued) and `last_skip` names why.
+    def mark_skip(id:, tenant:, agent:, reason:, next_fire_at:, now: Time.now.utc)
+      mutate(tenant, agent, id, now) do |record|
+        record["last_skip"] = { "at" => now.utc.iso8601, "reason" => reason.to_s }
+        record["next_fire_at"] = next_fire_at.iso8601
+      end
+    end
+
+    def delete(tenant:, agent:, id:)
+      @store.delete(SCOPE, key(tenant, agent, id))
+    end
+
+    # -> count removed. The LGPD sweep (a tenant's schedules die with it).
+    def purge(tenant:)
+      prefix = "#{tenant_id(tenant)}:"
+      keys = @store.list(SCOPE).select { |k| k.start_with?(prefix) }
+      keys.each { |k| @store.delete(SCOPE, k) }
+      keys.size
+    end
+
+    private
+
+    # Create or update ONE row from the declaration, recomputing next_fire_at
+    # on create and on any trigger/definition change. -> the schedule id.
+    def upsert(tenant:, agent:, schedule:, now:)
+      k = key(tenant, agent, schedule.id)
+      record = @store.get(SCOPE, k)
+      return schedule.id if record && !changed?(record, schedule)
+
+      next_fire_at = initial_next_fire(schedule, now)
+      row = {
+        "id" => schedule.id, "tenant" => tenant_id(tenant), "agent" => agent.to_s,
+        "every" => schedule.every, "cron" => schedule.cron, "tz" => schedule.tz,
+        "message" => schedule.message, "session_mode" => schedule.session_mode,
+        "session_id" => schedule.session_id, "overrides" => schedule.overrides,
+        "enabled" => schedule.enabled,
+        "next_fire_at" => next_fire_at&.iso8601,
+        "last_run_at" => record&.dig("last_run_at"),
+        "last_task_id" => record&.dig("last_task_id"),
+        "last_skip" => record&.dig("last_skip"),
+        "created_at" => record ? record["created_at"] : now.iso8601,
+        "updated_at" => now.iso8601
+      }
+      @store.set(SCOPE, k, row)
+      schedule.id
+    end
+
+    # Does the row's DECLARATION differ from the schedule? (runtime state is
+    # never part of the comparison.)
+    def changed?(record, schedule)
+      record["cron"] != schedule.cron || record["every"] != schedule.every ||
+        record["tz"] != schedule.tz || record["message"] != schedule.message ||
+        record["session_mode"] != schedule.session_mode ||
+        record["session_id"] != schedule.session_id ||
+        record["overrides"] != schedule.overrides ||
+        record["enabled"] != schedule.enabled
+    end
+
+    # The first fire after `now` for a schedule that has none yet: for `every`,
+    # one interval out; for cron, the next expression match. nil (a cron that
+    # can never fire) makes the row never due — `due` ignores a nil.
+    def initial_next_fire(schedule, now)
+      if schedule.every
+        now + schedule.every
+      else
+        Insika::Cron.new(schedule.cron).next_after(now, tz: schedule.tz)
+      end
+    end
+
+    def mutate(tenant, agent, id, now)
+      @store.transaction do
+        record = @store.get(SCOPE, key(tenant, agent, id))
+        raise Insika::NotFoundError, "schedule not found: #{tenant}:#{agent}:#{id}" if record.nil?
+
+        yield record
+        record["updated_at"] = now.utc.iso8601
+        @store.set(SCOPE, key(tenant, agent, id), record)
+        to_record(record)
+      end
+    end
+
+    def key(tenant, agent, id)
+      "#{tenant_id(tenant)}:#{agent.to_s}:#{id.to_s}"
+    end
+
+    def tenant_id(tenant)
+      t = tenant.to_s
+      t.empty? ? "platform" : t
+    end
+
+    def to_record(rec)
+      return nil if rec.nil?
+
+      Record.new(id: rec["id"], tenant: rec["tenant"], agent: rec["agent"],
+                 every: rec["every"], cron: rec["cron"], tz: rec["tz"],
+                 message: rec["message"], session_mode: rec["session_mode"],
+                 session_id: rec["session_id"], overrides: rec["overrides"],
+                 enabled: rec["enabled"] != false,
+                 next_fire_at: rec["next_fire_at"],
+                 last_run_at: rec["last_run_at"],
+                 last_task_id: rec["last_task_id"], last_skip: rec["last_skip"],
+                 created_at: rec["created_at"], updated_at: rec["updated_at"])
+    end
+  end
+end