samagotchi 0.157.0 → 0.159.0

data/lib/samagotchi/web/session_hub.rb

@@ -6,6 +6,7 @@ require "time"
 
 require_relative "../session"
 require_relative "../session_manager"
+require_relative "../schedules"
 require_relative "../bridge_client"
 require_relative "../worker_link"
 require_relative "../config"
@@ -105,6 +106,7 @@ module Samagotchi
         @dir_mtime = nil    # the state dir's mtime at the last glob
         @root_cache = {}    # folder → project root, for sessions saved before project_root
         @next_full_probe = nil
+        @next_schedule_tick = nil
         @wakeup = Queue.new # stop wakes the tick thread out of its sleep
         @thread = nil
         @stopped = false
@@ -148,6 +150,8 @@ module Samagotchi
             check_installed
           end
         end
+        # Outside the projection's lock: a firing can wait for a recap.
+        schedule_tick
         nil
       end
 
@@ -314,6 +318,22 @@ module Samagotchi
         nil
       end
 
+      # chi web can be the scheduler when the user opts in (schedule.auto_tick):
+      # the same tick cron runs, gated by schedule.tick_interval_minutes and
+      # sharing schedules.lock, so cron and the hub never both fire.
+      def schedule_tick
+        return unless Config.get("schedule.auto_tick")
+
+        now = @now.call
+        return if @next_schedule_tick && now < @next_schedule_tick
+
+        @next_schedule_tick = now + (Samagotchi::Schedules.tick_interval_minutes * 60)
+        Samagotchi::Schedules.new(state_dir: @state_dir).tick
+      rescue StandardError => e
+        Log.warn(:web, "schedule_tick_failed", error: e.class.name, msg: e.message)
+        nil
+      end
+
       # A change (the first look too, unless it finds nothing) is a `chi`
       # event: chi web's terminal line and the open tabs hear it.
       def check_installed

data/lib/samagotchi/worker.rb

@@ -374,7 +374,9 @@ module Samagotchi
                              # chi web's Stop asks about these before TERMed-ing
                              # the worker (its own holds routes).
                              on_holds: -> { @idle_exit&.stoppable_holds },
-                             on_holds_stop: -> { @hold_stop&.stop_all })
+                             on_holds_stop: -> { @hold_stop&.stop_all },
+                             # `chi schedule tick` asks this before firing.
+                             on_activity: method(:activity_snapshot))
       # What failed to load and what plugins showed as they loaded, now that
       # a UI can be there (a late one gets them in the snapshot).
       @engine.announce_load_events!
@@ -410,12 +412,12 @@ module Samagotchi
     #   there is no live SSE or in-process cancel/answer).
     # @param on_input [#call, nil] called after the Bridge queues a turn
     def start_bridge(engine:, state_dir:, session_id:, on_input: nil, on_command: nil, on_exit_request: nil,
-                     exit_discards: nil, exit_stopped: nil, on_holds: nil, on_holds_stop: nil)
+                     exit_discards: nil, exit_stopped: nil, on_holds: nil, on_holds_stop: nil, on_activity: nil)
       require_relative "bridge"
       Samagotchi::Bridge.new(
         engine: engine, state_dir: state_dir, session_id: session_id, input_format: SessionInbox::INPUT_FORMAT,
         on_input: on_input, on_command: on_command, on_exit_request: on_exit_request, exit_discards: exit_discards,
-        exit_stopped: exit_stopped, on_holds: on_holds, on_holds_stop: on_holds_stop
+        exit_stopped: exit_stopped, on_holds: on_holds, on_holds_stop: on_holds_stop, on_activity: on_activity
       ).start
     rescue StandardError => e
       Log.error(:bridge, "start_failed", echo: "Bridge: failed to start for session #{session_id}: #{e.class}: #{e.message}", sid: session_id, error: e.class.name)
@@ -426,6 +428,22 @@ module Samagotchi
       Degrade.call(:config, "idle_exit_minutes_unreadable") { Samagotchi::Config.get("session.idle_exit_minutes") }
     end
 
+    # What this worker is busy with right now, for GET /activity: the same
+    # signals WorkerIdleExit#hold reads. A schedule never holds a worker up,
+    # so +reminders+ and +tasks_holding+ are reported for the log but are not a
+    # reason for a tick to skip a firing.
+    # @return [Hash]
+    def activity_snapshot
+      {
+        turn_running: @engine.turn_running?,
+        input_pending: input_pending?,
+        awaiting_continue: @turn_flow.awaiting_continue?,
+        open_streams: @bridge&.open_streams.to_i,
+        reminders: @engine.reminder_store&.any? ? 1 : 0,
+        tasks_holding: Degrade.call(:worker, "activity_tasks_unreadable") { @task_wakes&.watch&.holding&.size.to_i }
+      }
+    end
+
     # The delegate children of this session that are running a turn or have
     # a live worker. ChildrenStatus.of scans the session files; this runs on
     # an exit request, not every pass.
@@ -1033,9 +1051,9 @@ module Samagotchi
                kept: "Its note stays for the user's next message.", mark: task_wake)
     end
 
-    # The idle loop's sleep: the fallback tick, or less while reports wait
-    # out the start grace.
-    def idle_wait = @wakes.idle_wait(@poll_interval) { wake_state == :due }
+    # The idle loop's sleep: the fallback tick, or less while reports or
+    # attached-context wakes wait out the start grace.
+    def idle_wait = @wakes.idle_wait(@poll_interval) { wake_state == :due || @inbound.context_wake_waiting? }
 
     # The wake budget is spent: the parent's UIs hear once that reports
     # wait for the next message.

data/lib/samagotchi/worker_boot.rb

@@ -3,9 +3,8 @@
 require_relative "session_manager"
 
 module Samagotchi
-  # WorkerBoot: the worker process, from run_session_loop (what the boot
-  # string SessionManager#worker_command writes runs, through
-  # SessionManager.run_session_loop) to what it does as it leaves (CROSS-VERSION
+  # WorkerBoot: the worker process, from the entry the boot string names
+  # (WorkerBoot.run_session_loop) to what it does as it leaves (CROSS-VERSION
   # CONTRACT: spec/worker_contract_spec.rb). It takes the session's OwnerLock,
   # leaves the spawner's process tree, installs the signals and the project
   # env, and runs the Worker (worker.rb loads only then, after the lock). Calls
@@ -14,7 +13,7 @@ module Samagotchi
   module WorkerBoot
     class << self
       # Run the session loop inside the forked process: the worker's main,
-      # which the boot string reaches through SessionManager.run_session_loop.
+      # which the boot string names directly.
       #
       # Every worker starts its per-session Bridge (the single live client
       # transport) on a port bound to 127.0.0.1 before the loop and stops it on

data/lib/samagotchi/worker_inbound.rb

@@ -106,6 +106,7 @@ module Samagotchi
       @stopped = stopped
       @queue_command = queue_command
       @initial_prompt_taken = false
+      @context_wake_waiting = false
     end
 
     # Add the queued context notes to the conversation (between turns only,
@@ -148,12 +149,18 @@ module Samagotchi
     # @return [ContextWake, nil] the wake turn to run now
     # @raise [SystemCallError, IOError] the caller logs it (context_failed)
     def absorb_context(before_turn: false, wake: false)
+      @context_wake_waiting = false
       return nil unless before_turn || conversation_started?
       return nil if @stopped.call
 
       batch = @context_absorber.pending
       return nil unless batch
 
+      if wake && context_wake_waiting_for?(batch)
+        @context_wake_waiting = true
+        return nil
+      end
+
       waking = wake ? context_wake_for(batch) : nil
       turn_id = SecureRandom.uuid if waking
       batch.deliveries.each do |delivery|
@@ -170,6 +177,10 @@ module Samagotchi
       waking && ContextWake.new(delivery: waking, turn_id: turn_id)
     end
 
+    # Whether #absorb_context left an eligible wake batch uncommitted for
+    # the start grace, so the idle loop can revisit it when grace expires.
+    def context_wake_waiting? = @context_wake_waiting
+
     # A failed wake turn kept nothing but its note: the note goes back to
     # a plain note (no turn start, the background wording), so a reload
     # draws no empty turn for it. +wake+: a ContextWake or a TaskWake.
@@ -300,6 +311,18 @@ module Samagotchi
       waking.first
     end
 
+    def context_wake_waiting_for?(batch)
+      return false unless @wakes.in_grace?
+
+      candidates = batch.deliveries.select(&:wake_note)
+      return false if candidates.empty? || !context_wakes_on?
+      return false unless @wakes.context_ready?(awaiting_continue: @awaiting_continue.call, names: candidates.map(&:name))
+
+      candidates.any? do |delivery|
+        delivery.peer ? @wakes.peer_in_a_row < @wakes.peer_turns : !woke_lately?(delivery.subscription, Time.now)
+      end
+    end
+
     # A peer's answer waits as a note: the UIs hear it once per
     # interactive input (WorkerWakes#notice_peer_budget!). +key+: the
     # budget that holds it.

data/lib/samagotchi/worker_link.rb

@@ -34,6 +34,11 @@ module Samagotchi
     # newer worker's (Skew).
     PROTOCOL = 1
 
+    # A worker whose sidecar publishes this may be asked what it is busy with
+    # (Bridge's GET /activity, Worker#activity_snapshot): a sidecar without it
+    # is an older chi's, and asking it would only cost a 404.
+    ACTIVITY_FEATURE = "activity"
+
     # Seconds a worker may hold the lock without publishing its Bridge before
     # Starting is stuck (SessionManager::WORKER_START_GRACE).
     START_LIMIT = 30.0

data/lib/samagotchi/worker_wakes.rb

@@ -101,7 +101,15 @@ module Samagotchi
     # not paused, past the start grace and under the budget. +names+: the
     # sources asking, for the log line when the budget holds them.
     def context_open?(awaiting_continue:, names:)
-      return false if @paused || awaiting_continue || in_grace?
+      return false if in_grace?
+
+      context_ready?(awaiting_continue:, names:)
+    end
+
+    # The context wake gates apart from start grace; used to decide whether
+    # a wake must remain pending until that grace ends.
+    def context_ready?(awaiting_continue:, names:)
+      return false if @paused || awaiting_continue
 
       if @in_a_row >= max
         Log.info(:worker, "context_wake_held", reason: "max_wakes", names: names.join(","))

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samagotchi
 version: !ruby/object:Gem::Version
-  version: 0.157.0
+  version: 0.159.0
 platform: ruby
 authors:
 - Dmitry Dedov
@@ -176,6 +176,7 @@ files:
 - docs/memory.md
 - docs/plugins.md
 - docs/releasing.md
+- docs/scheduling.md
 - docs/sessions.md
 - docs/sub-agent.md
 - docs/system-one.md
@@ -435,7 +436,6 @@ files:
 - lib/samagotchi/hook_question.rb
 - lib/samagotchi/hook_routes.rb
 - lib/samagotchi/hooks.rb
-- lib/samagotchi/hooks/bundle_loader.rb
 - lib/samagotchi/hooks/loader.rb
 - lib/samagotchi/hooks/registry.rb
 - lib/samagotchi/hooks/stream_watch.rb
@@ -500,6 +500,7 @@ files:
 - lib/samagotchi/log_subscriber.rb
 - lib/samagotchi/memory_bundle.rb
 - lib/samagotchi/memory_bundle/asset_installer.rb
+- lib/samagotchi/memory_bundle/asset_state.rb
 - lib/samagotchi/memory_bundle/builder.rb
 - lib/samagotchi/memory_bundle/bundle_hook.rb
 - lib/samagotchi/memory_bundle/entry_size.rb
@@ -592,7 +593,9 @@ files:
 - lib/samagotchi/plugin_tasks.rb
 - lib/samagotchi/private_files.rb
 - lib/samagotchi/process_group.rb
+- lib/samagotchi/project_command.rb
 - lib/samagotchi/project_env.rb
+- lib/samagotchi/project_init.rb
 - lib/samagotchi/project_scope.rb
 - lib/samagotchi/prompt.rb
 - lib/samagotchi/prompt_files.rb
@@ -639,6 +642,8 @@ files:
 - lib/samagotchi/run_options.rb
 - lib/samagotchi/sampling_settings.rb
 - lib/samagotchi/sandbox_layout.rb
+- lib/samagotchi/schedule_command.rb
+- lib/samagotchi/schedules.rb
 - lib/samagotchi/self_report.rb
 - lib/samagotchi/send_command.rb
 - lib/samagotchi/send_command/busy.rb
@@ -801,6 +806,7 @@ files:
 - lib/samagotchi/tools/builtin_calls.rb
 - lib/samagotchi/tools/builtins.rb
 - lib/samagotchi/tools/cancel_reminder.rb
+- lib/samagotchi/tools/cancel_schedule.rb
 - lib/samagotchi/tools/context_read.rb
 - lib/samagotchi/tools/deferred_tools.rb
 - lib/samagotchi/tools/delegate.rb
@@ -813,6 +819,7 @@ files:
 - lib/samagotchi/tools/forget_outputs.rb
 - lib/samagotchi/tools/index_hint.rb
 - lib/samagotchi/tools/list_reminders.rb
+- lib/samagotchi/tools/list_schedules.rb
 - lib/samagotchi/tools/list_sessions.rb
 - lib/samagotchi/tools/memory.rb
 - lib/samagotchi/tools/objectives_tool.rb
@@ -822,6 +829,7 @@ files:
 - lib/samagotchi/tools/ref_text.rb
 - lib/samagotchi/tools/register_reminder.rb
 - lib/samagotchi/tools/registry.rb
+- lib/samagotchi/tools/schedule_task.rb
 - lib/samagotchi/tools/send_note.rb
 - lib/samagotchi/tools/shell.rb
 - lib/samagotchi/tools/task_create.rb

data/lib/samagotchi/hooks/bundle_loader.rb

@@ -1,191 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "registry"
-require "digest"
-require_relative "../log"
-require_relative "../guardrails/load_failures"
-require_relative "../memory_bundle/bundle_hook"
-require_relative "../memory_bundle/provenance"
-
-module Samagotchi
-  # Namespace that wraps hook plugin classes per-bundle. Each bundle's hooks are
-  # evaluated inside `Samagotchi::Bundles::<BundleName>` so that two bundles
-  # shipping a file with the same basename (e.g. `guardrails.rb`) cannot collide
-  # on a top-level constant.
-  module Bundles; end
-
-  module Hooks
-    # Loads bundle-owned hook plugins into a Registry.
-    #
-    # Unlike +Hooks::Loader+ (which `require`s a file and resolves a top-level
-    # constant), this loader `module_eval`s each plugin file inside a
-    # per-bundle namespace module. This gives:
-    #   - zero class-name collisions across bundles
-    #   - a clean uninstall path (`Registry#unregister_bundle`)
-    #
-    # Each plugin must define a class whose PascalCase name matches the file
-    # basename and whose instances respond to +call(event)+.
-    #
-    # A "fail_closed" before_tool_call hook is required: if it is missing,
-    # fails to load, or its file's sha256 differs from the one recorded at
-    # install, the failure is reported and the gate denies every tool call.
-    # Any hook whose sha256 differs is not loaded (reinstall the bundle
-    # after editing a hook by hand), nor any of a bundle whose requires_chi
-    # this chi doesn't meet.
-    #
-    # The +on_error+ policy is applied per hook at fire time (Hooks.wrap):
-    #   - "fail_closed" (on :before_tool_call): a raising guardrail denies
-    #     the tool call (fail-closed).
-    #   - "log": warn to stderr and continue.
-    #   - "skip" (default): silently continue.
-    # Whatever the policy, a hook file that raises is told to the user once
-    # per hook (its +hook_failed+ callback, the Engine's
-    # HookRoutes#plugin_hook_failed): :skip would otherwise leave no trace.
-    module BundleLoader
-      class << self
-        # Load all hook plugins for a bundle into the given registry.
-        #
-        # @param bundle_name [String]
-        # @param hooks_dir [String] directory containing the bundle's .rb hook files
-        # @param metadata [Hash] basename => { event:, on_error:, priority:,
-        #   sha256: } (MemoryBundle::BundleHook.parse reads it)
-        # @param registry [Samagotchi::Hooks::Registry]
-        # @param failures [Guardrails::LoadFailures, nil] collects hooks that
-        #   failed to load
-        # @param settings [Hash] the bundle's section of config.yml
-        #   `bundles:` (string keys); a hook class whose initialize takes an
-        #   argument gets it
-        # @param manifest [MemoryBundle::InstalledManifest, nil] the installed
-        #   bundle's manifest; when this chi doesn't meet its requires_chi no
-        #   hook loads (each is reported, as the plugin loader does)
-        # @param hook_failed [#call, nil] (label, "Class: message", effect:)
-        #   when a hook file raises at fire time — the Engine's HookRoutes;
-        #   nil when there is no UI to tell (the test kit)
-        # @return [Integer] number of hooks successfully registered
-        def load(bundle_name:, hooks_dir:, metadata:, registry:, failures: nil, settings: {}, manifest: nil, hook_failed: nil)
-          return 0 unless metadata.is_a?(Hash)
-
-          too_old = manifest&.requires_chi_failure
-          loaded = 0
-          metadata.each do |raw_basename, raw_meta|
-            basename = raw_basename.to_s
-            next if basename.empty?
-
-            hook = MemoryBundle::BundleHook.parse(raw_meta)
-            # A hook with no declared event cannot be auto-registered.
-            next if hook.events.empty?
-
-            fail_closed = hook.events.any? { |event| hook.fail_closed?(event) }
-            what = "hook #{basename} (bundle #{bundle_name})"
-            file = hooks_dir && File.join(hooks_dir, basename)
-            unless file && File.exist?(file)
-              failures&.add(what, "the file is missing", required: true) if fail_closed
-              next
-            end
-            if (mismatch = too_old || sha_mismatch(file, hook.sha256, required: fail_closed))
-              Log.warn(:hooks, "bundle_hook_mismatch", echo: "[samagotchi:hooks] bundle '#{bundle_name}' hook '#{basename}' not loaded: #{mismatch}", bundle: bundle_name, hook: basename.to_s)
-              failures&.add(what, mismatch, required: fail_closed)
-              next
-            end
-
-            begin
-              load_hook_file(bundle_name, basename, file, hook, registry, settings: settings, hook_failed: hook_failed)
-              loaded += 1
-            rescue Exception => e # rubocop:disable Lint/RescueException -- a hook's SyntaxError or exit must not stop chi
-              raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
-
-              Log.error(:hooks, "bundle_hook_load_failed", echo: "[samagotchi:hooks] bundle '#{bundle_name}' hook '#{basename}' failed to load: #{e.class}: #{e.message}", bundle: bundle_name, hook: basename.to_s, error: e.class.name)
-              failures&.add(what, "#{e.class}: #{e.message}", required: fail_closed,
-                                  location: Guardrails::LoadFailures.location(e, File.dirname(hooks_dir)))
-            end
-          end
-          loaded
-        end
-
-        # Build one hook file and register it in +registry+ under each of
-        # its events (one instance for all: its state is shared), with its
-        # priority and error policy (a fail_closed before_tool_call one
-        # denies when it raises). No missing-file, sha or requires_chi
-        # check: #load makes them; the test kit loads a bundle's source
-        # this way.
-        # @param hook [MemoryBundle::BundleHook] its manifest entry
-        # @param namespace [Module, nil] the module the file is evaluated
-        #   in (default: the bundle's, #namespace_for)
-        # @param hook_failed [#call, nil] (label, "Class: message", effect:)
-        #   on every raise at fire time, whatever the policy; nil gives no
-        #   notice (the log still has a :log hook's failures)
-        # @raise [Exception] what loading or building the file raised;
-        #   nothing is registered then
-        def load_hook_file(bundle_name, basename, file, hook, registry, settings: {}, namespace: nil, hook_failed: nil)
-          plugin = instantiate(bundle_name, basename, file, settings: settings, namespace: namespace)
-          hook.events.each do |event_name|
-            event_sym = event_name.to_sym
-            fail_closed = hook.fail_closed?(event_sym)
-            policy = if fail_closed then :deny
-                     elsif hook.on_error == "log" then :log
-                     else :skip
-                     end
-            label = "#{"guardrail " if fail_closed}#{basename} (bundle #{bundle_name})"
-            # Every policy tells, once per label: a hook file under the
-            # default :skip would raise with no trace anywhere. The label
-            # names the file, the bundle and the event, so one label per
-            # hook and a stream hook can't nag.
-            on_failure = hook_failed && lambda { |hook_label, failed|
-              hook_failed.call("#{hook_label} #{event_sym} hook", failed, effect: policy)
-            }
-            handler = Hooks.wrap(label: label, event: event_sym, policy: policy, log: [:hooks, "bundle_hook_failed"],
-                                 fields: { bundle: bundle_name }, on_failure: on_failure) { |event| plugin.call(event) }
-            registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: hook.priority, &handler)
-          end
-          nil
-        end
-
-        # Why the file doesn't match the sha256 recorded at install, or nil.
-        # With none recorded, only a required hook counts as a mismatch.
-        def sha_mismatch(file, recorded, required:)
-          return nil if MemoryBundle::Provenance.unchecked?(recorded)
-
-          expected = MemoryBundle::Provenance.recorded_sha(recorded)
-          return (required ? "no sha256 recorded for it (reinstall the bundle)" : nil) if expected.empty?
-
-          actual = MemoryBundle::Provenance.file_sha(file)
-          return nil if actual == expected
-
-          "its sha256 #{actual[0, 12]}… differs from the installed #{expected[0, 12]}… (edited after install? reinstall the bundle)"
-        end
-
-        # Evaluate a plugin file inside the bundle's namespace module (or
-        # +namespace+) and
-        # return an instance that responds to #call. A class whose
-        # initialize takes an argument gets the settings (one Hash, string
-        # keys); one that takes none is built bare.
-        def instantiate(bundle_name, basename, file, settings: {}, namespace: nil)
-          ns = namespace || namespace_for(bundle_name)
-          content = File.read(file)
-          ns.module_eval(content, file, 1)
-          klass = Hooks.class_for(basename, ns)
-          instance = Hooks.build_plugin(klass, settings)
-          raise ArgumentError, "plugin #{klass.name.split("::").last} does not respond to #call" unless instance.respond_to?(:call)
-
-          instance
-        end
-
-        # The (lazily created) namespace module for a bundle.
-        # Sanitization is made injective by appending a short digest so that
-        # `my-bundle` and `my_bundle` do not collide.
-        def namespace_for(bundle_name)
-          raw = bundle_name.to_s
-          base = raw.gsub(/[^A-Za-z0-9_]/, "_")
-          base = "B_#{base}" unless base.match?(/\A[A-Z]/)
-          digest = Digest::MD5.hexdigest(raw)[0, 4]
-          ns_name = "#{base}_#{digest}"
-          if Samagotchi::Bundles.const_defined?(ns_name.to_sym, false)
-            Samagotchi::Bundles.const_get(ns_name.to_sym)
-          else
-            Samagotchi::Bundles.const_set(ns_name.to_sym, Module.new)
-          end
-        end
-      end
-    end
-  end
-end