robot_lab-am 0.0.1

data/lib/robot_lab/am/cli.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Am
+    # Entry point for the `am` executable.
+    #
+    # `snapshot` is the one-shot collect + infer + write. `start`/`stop`/
+    # `status` manage the continuous daemon (DaemonController), and
+    # `install`/`uninstall` manage the launchd agent that supervises it.
+    # Factories are injectable so tests can exercise dispatch without forking
+    # processes or touching ~/Library.
+    class CLI
+      COMMANDS = %w[snapshot start stop status install uninstall].freeze
+
+      def self.run(argv = ARGV)
+        new.run(argv)
+      end
+
+      def initialize(controller_factory: nil, launchd_factory: nil)
+        @controller_factory = controller_factory
+        @launchd_factory = launchd_factory
+      end
+
+      # :reek:TooManyStatements -- the flag/guard/dispatch sequence reads
+      # best as one method; each statement is a distinct early return.
+      def run(argv)
+        command = argv.first
+        return puts("am #{VERSION}") if %w[--version -v].include?(command)
+        return puts(usage) if command.nil? || %w[--help -h].include?(command)
+
+        unless COMMANDS.include?(command)
+          warn "Unknown command: #{command.inspect}"
+          warn usage
+          exit 1
+        end
+
+        dispatch(command, parse_options(argv[1..]))
+      rescue Error => e
+        warn e.message
+        exit 1
+      end
+
+      private
+
+      # :reek:ControlParameter :reek:DuplicateMethodCall -- a dispatcher is
+      # controlled by its command by definition, and only one case branch
+      # (hence one controller build) ever runs per invocation.
+      def dispatch(command, options)
+        case command
+        when "snapshot"  then run_snapshot(options)
+        when "start"     then puts controller(options).start(foreground: options[:foreground])
+        when "stop"      then puts controller(options).stop
+        when "status"    then puts controller(options).status
+        when "install"   then run_install(options)
+        when "uninstall" then run_uninstall(options)
+        end
+      end
+
+      def controller_factory
+        @controller_factory ||= ->(options) { DaemonController.new(**options.slice(:repo, :interval, :debounce)) }
+      end
+
+      def launchd_factory
+        @launchd_factory ||= ->(options) { Launchd.new(**options.slice(:repo, :interval, :debounce)) }
+      end
+
+      def controller(options)
+        controller_factory.call(options)
+      end
+
+      def config
+        @config ||= Am.config
+      end
+
+      def run_snapshot(options)
+        repo = options[:repo]
+        event_log = EventLog.new(File.join(repo, ".robot_lab_am", "events.jsonl"))
+        new_events = Collector.new(repo: repo, event_log: event_log, config: config).collect_new
+
+        intent = Inferrer.new(config: config).infer(event_log.all.last(config.inference_window), repo: repo)
+        path   = IntentWriter.new(repo: repo).write(intent)
+
+        report_snapshot(repo, new_events, path)
+      end
+
+      def report_snapshot(repo, new_events, path)
+        puts "Collected #{new_events.size} new event(s) from #{repo}"
+        puts "Wrote #{path}"
+        puts ""
+        puts File.read(path)
+      end
+
+      def run_install(options)
+        launchd = launchd_factory.call(options)
+        path = launchd.install
+        puts <<~MSG
+          Wrote #{path}
+          Load it now (and on every login) with:
+            launchctl bootstrap gui/#{Process.uid} #{path}
+          Unload it with:
+            launchctl bootout gui/#{Process.uid}/#{launchd.label}
+        MSG
+      end
+
+      def run_uninstall(options)
+        launchd = launchd_factory.call(options)
+        path = launchd.uninstall
+        puts <<~MSG
+          Removed #{path}
+          If the agent was loaded, unload it with:
+            launchctl bootout gui/#{Process.uid}/#{launchd.label}
+        MSG
+      end
+
+      # :reek:FeatureEnvy :reek:TooManyStatements -- an option parser's whole
+      # job is filling the options hash, one statement per flag.
+      # interval/debounce stay nil unless flagged — downstream they fall
+      # through to Am::Config (user config file / RLAM_* env vars).
+      def parse_options(args)
+        options = { repo: Dir.pwd, foreground: false, interval: nil, debounce: nil }
+        args = args.dup
+        until args.empty?
+          arg = args.shift
+          case arg
+          when "--repo"       then options[:repo] = required_value(args, arg)
+          when "--interval"   then options[:interval] = integer_value(args, arg)
+          when "--debounce"   then options[:debounce] = integer_value(args, arg)
+          when "--foreground" then options[:foreground] = true
+          else raise Error, "Unknown option: #{arg.inspect}"
+          end
+        end
+        options[:repo] = File.expand_path(options[:repo])
+        options
+      end
+
+      # :reek:FeatureEnvy -- validating the shifted value is this method's
+      # entire job.
+      def required_value(args, flag)
+        value = args.shift
+        raise Error, "#{flag} requires a value" if value.nil? || value.start_with?("--")
+
+        value
+      end
+
+      def integer_value(args, flag)
+        Integer(required_value(args, flag))
+      rescue ArgumentError
+        raise Error, "#{flag} requires an integer value"
+      end
+
+      def usage
+        <<~USAGE
+          Usage: am COMMAND [options]
+
+          Commands:
+            snapshot   One-shot: collect new git/terminal/Claude Code activity, infer the
+                       current goal, and write .robot_lab_am/current_intent.md
+            start      Start the activity-monitor daemon for the repo
+                       (--foreground to run in this terminal instead of detaching)
+            stop       Stop the running daemon
+            status     Show whether the daemon is running, with heartbeat detail
+            install    Write a launchd agent plist so the daemon runs at login
+            uninstall  Remove the launchd agent plist
+
+          Options:
+            --repo PATH    Repo to watch (default: current directory)
+            --interval N   Seconds between daemon polls (currently: #{config.interval})
+            --debounce N   Minimum seconds between inference runs (currently: #{config.debounce})
+            --foreground   With start: run the daemon without detaching
+            -h, --help     Show this help
+            -v, --version  Print version and exit
+
+          Configuration cascade (lowest to highest precedence): bundled
+          defaults -> ~/.config/robot_lab_am/robot_lab_am.yml ->
+          RLAM_* env vars -> the flags above.
+        USAGE
+      end
+    end
+  end
+end

data/lib/robot_lab/am/collector.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Am
+    # One collection pass over all three watchers: redacts each event, drops
+    # anything already in the event log (by Event#fingerprint), and appends
+    # what's genuinely new. Both the one-shot `am snapshot` and every daemon
+    # tick go through here, so repeated runs never duplicate log lines.
+    class Collector
+      def initialize(repo:, event_log:, watchers: nil, config: nil)
+        @repo = repo
+        @event_log = event_log
+        @watchers = watchers
+        @config = config
+      end
+
+      # Returns the new events, already redacted and appended to the log.
+      def collect_new
+        fresh = watchers.flat_map(&:events)
+                        .map { |event| Redactor.redact_event(event) }
+                        .reject { |event| seen.include?(event.fingerprint) }
+        fresh.each do |event|
+          @event_log.append(event)
+          seen << event.fingerprint
+        end
+        fresh
+      end
+
+      private
+
+      # Seeded once from the existing log so a restart doesn't re-append
+      # history; maintained incrementally after that.
+      def seen
+        @seen ||= @event_log.all.to_set(&:fingerprint)
+      end
+
+      def config = @config ||= Am.config
+
+      def watchers
+        @watchers ||= [
+          Watchers::GitWatcher.new(repo: @repo),
+          Watchers::ClaudeWatcher.new(repo: @repo),
+          Watchers::TerminalWatcher.new(repo: @repo, log_path: config.terminal_log)
+        ]
+      end
+    end
+  end
+end

data/lib/robot_lab/am/config/defaults.yml

@@ -0,0 +1,18 @@
+defaults:
+  provider: openai                                   # RubyLLM provider for inference
+  model: qwen/qwen3.8-27b                            # local model served by LM Studio
+  api_base: http://localhost:1234/v1                 # OpenAI-compatible local server
+  api_key: null                                      # null = provider env var, or none (local)
+  interval: 15                                       # seconds between daemon watcher polls
+  debounce: 300                                      # minimum seconds between inference runs
+  inference_window: 100                              # most recent events sent to the model
+  terminal_log: ~/.activity_monitor/terminal_activity.log  # preexec command log
+
+development:
+  {}
+
+test:
+  {}
+
+production:
+  {}

data/lib/robot_lab/am/config.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "myway_config"
+
+module RobotLab
+  module Am
+    # Configuration for the activity monitor, following the same
+    # MywayConfig::Base pattern as robot_lab-to's Config.
+    #
+    # Sources (lowest to highest precedence):
+    #   1. Bundled defaults (config/defaults.yml)
+    #   2. User config file (~/.config/robot_lab_am/robot_lab_am.yml,
+    #      or $XDG_CONFIG_HOME/robot_lab_am/robot_lab_am.yml)
+    #   3. Environment variables (RLAM_*)
+    #   4. Constructor keyword arguments (CLI flag overrides)
+    #
+    # :reek:InstanceVariableAssumption -- the defaults.yml-backed ivars ARE
+    # assigned, by `super()` (MywayConfig::Base / Anyway::Config), before any
+    # of this class's own code runs. Do NOT pre-nil them in #initialize:
+    # that overwrites the real loaded values with nil (robot_lab-to's Config
+    # carries the same caveat).
+    class Config < MywayConfig::Base
+      config_name :robot_lab_am
+      env_prefix :rlam
+      defaults_path File.expand_path("config/defaults.yml", __dir__)
+      auto_configure!
+
+      # auto_configure! only derives symbol/boolean/section coercions from
+      # the YAML value types; the integer settings and the string-to-symbol
+      # provider need explicit coercion so RLAM_* env values (always
+      # strings) come out typed.
+      coerce_types provider: to_symbol, interval: :integer,
+                   debounce: :integer, inference_window: :integer
+
+      # Runtime CLI overrides — applied after load. A nil override is
+      # ignored (see #initialize), so CLI code can pass flags through
+      # unconditionally.
+      attr_writer :provider, :model, :api_base, :api_key, :interval, :debounce,
+                  :inference_window, :terminal_log
+
+      def initialize(**overrides)
+        super()
+        overrides.each { |key, value| public_send(:"#{key}=", value) unless value.nil? }
+      end
+
+      def provider         = @provider || super
+      def model            = @model || super
+      def api_base         = @api_base || super
+      def api_key          = @api_key || super
+      def interval         = @interval || super
+      def debounce         = @debounce || super
+      def inference_window = @inference_window || super
+
+      # Expanded at read time so "~" works from YAML, env, and overrides alike.
+      def terminal_log = File.expand_path(@terminal_log || super)
+    end
+  end
+end

data/lib/robot_lab/am/daemon.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "time"
+
+module RobotLab
+  module Am
+    # The continuous activity-monitor loop for one repo (ARCHITECTURE.md's
+    # Deployment model): poll the watchers, append new events, and re-infer
+    # the current intent on a debounced cadence.
+    #
+    # Cadence (resolves ARCHITECTURE.md open question 1): inference runs only
+    # when new events have arrived since the last inference, and at most once
+    # per `debounce` seconds — never per keystroke-equivalent event. The first
+    # activity after startup infers immediately.
+    #
+    # Every collaborator is injectable so #tick is testable in isolation with
+    # no LLM, no signals, and no sleeping. Tunables (interval, debounce,
+    # inference window) default from Am::Config when not passed explicitly.
+    class Daemon
+      # :reek:LongParameterList -- one keyword per collaborator is the price
+      # of #tick being testable in isolation; defaults resolve lazily below.
+      def initialize(repo:, config: nil, interval: nil, debounce: nil,
+                     event_log: nil, collector: nil, inferrer: nil, intent_writer: nil,
+                     pid_file: nil, heartbeat: nil)
+        @repo = repo
+        @config = config
+        @interval = interval
+        @debounce = debounce
+        @event_log = event_log
+        @collector = collector
+        @inferrer = inferrer
+        @intent_writer = intent_writer
+        @pid_file = pid_file
+        @heartbeat = heartbeat
+        @stop = false
+        @dirty = false
+        @events_total = 0
+        @last_inference_at = nil
+      end
+
+      def run
+        pid_file.write
+        trap_signals
+        until @stop
+          tick
+          wait
+        end
+      ensure
+        pid_file.delete
+      end
+
+      def stop!
+        @stop = true
+      end
+
+      # One poll cycle. Public so tests (and future callers) can drive the
+      # loop without running it.
+      def tick(now: Time.now)
+        new_events = collector.collect_new
+        @events_total += new_events.size
+        @dirty = true unless new_events.empty?
+        beat # before inference — a slow LLM call must not make a live daemon look dead
+        return unless infer_due?(now)
+
+        infer(now)
+        beat
+      end
+
+      private
+
+      def state_path(file)
+        File.join(@repo, ".robot_lab_am", file)
+      end
+
+      def config    = @config ||= Am.config
+      def interval  = @interval || config.interval
+      def debounce  = @debounce || config.debounce
+
+      def event_log = @event_log ||= EventLog.new(state_path("events.jsonl"))
+      def collector = @collector ||= Collector.new(repo: @repo, event_log: event_log, config: config)
+      def inferrer = @inferrer ||= Inferrer.new(config: config)
+      def intent_writer = @intent_writer ||= IntentWriter.new(repo: @repo)
+      def pid_file = @pid_file ||= PidFile.new(state_path("daemon.pid"))
+      def heartbeat = @heartbeat ||= Heartbeat.new(state_path("heartbeat.json"))
+
+      def beat
+        heartbeat.beat(pid: Process.pid, events_total: @events_total,
+                       last_inference_at: @last_inference_at&.utc&.iso8601)
+      end
+
+      def infer_due?(now)
+        @dirty && (@last_inference_at.nil? || now - @last_inference_at >= debounce)
+      end
+
+      # A failed inference (LLM server down, malformed response) must not kill
+      # the daemon; leaving @dirty set retries it once the next debounce
+      # window opens, and stamping @last_inference_at anyway is what spaces
+      # those retries out.
+      def infer(now)
+        window = event_log.all.last(config.inference_window)
+        intent_writer.write(inferrer.infer(window, repo: @repo))
+        @dirty = false
+      rescue StandardError => e
+        warn "[robot_lab-am] inference failed: #{e.class}: #{e.message}"
+      ensure
+        @last_inference_at = now
+      end
+
+      def wait
+        sleep(interval) unless @stop
+      end
+
+      def trap_signals
+        %w[TERM INT].each { |signal| Signal.trap(signal) { @stop = true } }
+      end
+    end
+  end
+end

data/lib/robot_lab/am/daemon_controller.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module RobotLab
+  module Am
+    # Process management behind `am start|stop|status`: forks and detaches the
+    # Daemon, tears it down with SIGTERM, and reports liveness from the pid
+    # file plus the heartbeat. Methods return a human-readable message on
+    # success and raise Am::Error on failure — the CLI turns those into
+    # stdout/exit codes.
+    #
+    # :reek:RepeatedConditional -- daemon liveness (@pid_file.alive?) is
+    # deliberately re-checked at each lifecycle boundary (start guard, stop,
+    # status); caching it would defeat the point.
+    class DaemonController
+      START_TIMEOUT_SECONDS = 10
+      STOP_TIMEOUT_SECONDS = 10
+
+      def initialize(repo:, interval: nil, debounce: nil,
+                     daemon_factory: nil, spawner: nil)
+        @repo = repo
+        @interval = interval
+        @debounce = debounce
+        @pid_file = PidFile.new(File.join(state_dir, "daemon.pid"))
+        @heartbeat = Heartbeat.new(File.join(state_dir, "heartbeat.json"))
+        @daemon_factory = daemon_factory
+        @spawner = spawner
+      end
+
+      # :reek:BooleanParameter :reek:ControlParameter -- mirrors the CLI's
+      # --foreground flag; both paths share the already-running guard.
+      def start(foreground: false)
+        raise Error, "daemon already running for #{@repo} (pid #{@pid_file.read})" if @pid_file.alive?
+
+        @pid_file.delete
+        return run_foreground if foreground
+
+        run_background
+      end
+
+      def stop
+        pid = @pid_file.read
+        raise Error, "daemon not running for #{@repo}" unless pid
+
+        unless @pid_file.alive?
+          @pid_file.delete
+          raise Error, "daemon not running for #{@repo} (removed stale pid file for pid #{pid})"
+        end
+
+        Process.kill("TERM", pid)
+        wait_until(STOP_TIMEOUT_SECONDS, "daemon (pid #{pid}) did not exit within #{STOP_TIMEOUT_SECONDS}s") do
+          !@pid_file.alive?
+        end
+        "stopped daemon for #{@repo} (pid #{pid})"
+      end
+
+      def status
+        unless @pid_file.alive?
+          suffix = @pid_file.exist? ? " (stale pid file: #{@pid_file.read})" : ""
+          raise Error, "daemon not running for #{@repo}#{suffix}"
+        end
+
+        ["daemon running for #{@repo} (pid #{@pid_file.read})", *heartbeat_lines].join("\n")
+      end
+
+      private
+
+      def daemon_factory = @daemon_factory ||= method(:build_daemon)
+      def spawner = @spawner ||= method(:spawn_daemon)
+
+      def state_dir
+        File.join(@repo, ".robot_lab_am")
+      end
+
+      def log_path
+        File.join(state_dir, "daemon.log")
+      end
+
+      # nil interval/debounce fall through to the Daemon's Am::Config lookup.
+      def build_daemon
+        Daemon.new(repo: @repo, interval: @interval, debounce: @debounce)
+      end
+
+      def run_foreground
+        daemon_factory.call.run
+        "daemon for #{@repo} exited"
+      end
+
+      def run_background
+        child = spawner.call
+        Process.detach(child)
+        wait_until(START_TIMEOUT_SECONDS, "daemon did not start within #{START_TIMEOUT_SECONDS}s — see #{log_path}") do
+          @pid_file.alive?
+        end
+        "started daemon for #{@repo} (pid #{@pid_file.read}), logging to #{log_path}"
+      end
+
+      # The double fork: the forked child detaches from the terminal via
+      # Process.daemon, then runs the loop. exit! (not exit) so the child
+      # never runs at_exit hooks inherited from the parent process.
+      def spawn_daemon
+        fork do
+          Process.daemon(true)
+          redirect_output
+          exit!(run_daemon_safely)
+        end
+      end
+
+      # Exit status for the daemonized child — 0 for a clean stop, 1 for a
+      # crash, with the crash recorded in the log file.
+      # :reek:FeatureEnvy -- formatting the caught exception for the log
+      # inherently reads `e` more than self.
+      def run_daemon_safely
+        daemon_factory.call.run
+        0
+      rescue StandardError => e
+        warn "[robot_lab-am] daemon crashed: #{e.class}: #{e.message}"
+        warn e.backtrace.join("\n") if e.backtrace
+        1
+      end
+
+      def redirect_output
+        FileUtils.mkdir_p(File.dirname(log_path))
+        $stdout.reopen(log_path, "a")
+        $stderr.reopen(log_path, "a")
+        $stdout.sync = true
+        $stderr.sync = true
+      end
+
+      def heartbeat_lines
+        data = @heartbeat.read
+        return [] unless data
+
+        [
+          "  heartbeat: #{@heartbeat.age}s ago",
+          "  events logged since start: #{data['events_total']}",
+          "  last inference: #{data['last_inference_at'] || 'never'}"
+        ]
+      end
+
+      def wait_until(timeout, failure_message)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        until yield
+          raise Error, failure_message if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+          sleep 0.1
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/am/event.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Am
+    # One normalized activity signal, per the shape decided in
+    # ARCHITECTURE.md's "Ingestion & normalization" section.
+    Event = Data.define(:timestamp, :repo, :source, :kind, :summary) do
+      def to_h_json
+        { timestamp: timestamp, repo: repo, source: source, kind: kind, summary: summary }
+      end
+
+      # Identity for read-side dedupe (Collector). "wip" events are stamped
+      # with collection time, so two reads of the same dirty tree never share
+      # a timestamp — their identity is the summary alone.
+      def fingerprint
+        parts = [repo, source, kind, summary]
+        parts << timestamp unless kind == "wip"
+        parts.join("\x1F")
+      end
+    end
+  end
+end

data/lib/robot_lab/am/event_log.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module RobotLab
+  module Am
+    # Append-only JSONL event store — one Event per line. Chosen over SQLite
+    # per ARCHITECTURE.md's Storage section: the only consumer is an LLM
+    # summarization pass over a bounded recent window, not ad hoc queries.
+    class EventLog
+      def initialize(path)
+        @path = path
+      end
+
+      def append(event)
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.open(@path, "a") { |f| f.puts(event.to_h_json.to_json) }
+      end
+
+      def append_all(events)
+        events.each { |event| append(event) }
+      end
+
+      def all
+        return [] unless File.exist?(@path)
+
+        File.readlines(@path).filter_map { |line| parse_line(line) }
+      end
+
+      private
+
+      def parse_line(line)
+        Event.new(**JSON.parse(line, symbolize_names: true))
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/robot_lab/am/heartbeat.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "fileutils"
+
+module RobotLab
+  module Am
+    # The daemon's liveness record (.robot_lab_am/heartbeat.json), rewritten
+    # every tick — the "heartbeat row/line" ARCHITECTURE.md's Deployment model
+    # section calls for, so `am status` can tell a live daemon from a stale
+    # pid file left by a crash.
+    class Heartbeat
+      def initialize(path)
+        @path = path
+      end
+
+      def beat(pid:, events_total:, last_inference_at:)
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, JSON.generate(
+                            pid: pid,
+                            updated_at: Time.now.utc.iso8601,
+                            events_total: events_total,
+                            last_inference_at: last_inference_at
+                          ))
+      end
+
+      def read
+        return nil unless File.exist?(@path)
+
+        JSON.parse(File.read(@path))
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Seconds since the last beat, or nil when there has been none.
+      def age
+        updated_at = read&.fetch("updated_at", nil)
+        return nil unless updated_at
+
+        (Time.now.utc - Time.parse(updated_at)).round
+      end
+    end
+  end
+end