robot_lab-am 0.0.1

data/lib/robot_lab/am/inferrer.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "ruby_llm"
+
+module RobotLab
+  module Am
+    # Summarizes a bounded window of Events into a structured Intent with a
+    # one-shot RubyLLM chat — no robots, no robot_lab dependency, so the gem
+    # is useful outside the robot_lab-to environment too. `chat:` is
+    # injectable so callers (and tests) never have to make a real LLM call
+    # to exercise this class.
+    #
+    # Provider, model, API base, and key come from Am::Config (defaults.yml
+    # -> user config file -> RLAM_* env vars -> keyword overrides).
+    # The shipped default is a local model served by LM Studio's
+    # OpenAI-compatible API (`lms server start`), not a hosted provider —
+    # inference over your own activity log shouldn't require sending it,
+    # or an API key, anywhere.
+    class Inferrer
+      # LM Studio ignores the key but RubyLLM's :openai provider requires
+      # one to be configured; used only when neither the config nor the
+      # provider's conventional env var supplies a real key.
+      PLACEHOLDER_API_KEY = "no-key-required"
+
+      SYSTEM_PROMPT = <<~PROMPT
+        You infer what a software developer is currently working on from a
+        timestamped activity log: their own git commits and uncommitted
+        changes, their own messages in a Claude Code session, and commands
+        they ran in a terminal. Respond with ONLY YAML, no other text, in
+        exactly this shape:
+
+        goal: <one or two sentences on what they're currently working toward>
+        confidence: <low|medium|high>
+        evidence:
+          - <short reference to a specific event that supports the goal>
+        open_questions:
+          - <anything ambiguous or unresolved>
+      PROMPT
+
+      def initialize(chat: nil, config: nil, model: nil, provider: nil)
+        @chat = chat
+        @config = config
+        @model = model
+        @provider = provider
+      end
+
+      def infer(events, repo:)
+        return empty_intent if events.empty?
+
+        parse(chat.ask(build_prompt(events, repo)).content)
+      end
+
+      private
+
+      def chat
+        @chat ||= build_chat
+      end
+
+      def config   = @config ||= Am.config
+      def model    = @model || config.model
+      def provider = @provider || config.provider
+
+      # assume_model_exists: local model names aren't in RubyLLM's registry.
+      def build_chat
+        llm_context.chat(model: model, provider: provider, assume_model_exists: true)
+                   .with_instructions(SYSTEM_PROMPT)
+      end
+
+      # A scoped RubyLLM context (a dup of the global config), so embedding
+      # robot_lab-am in a larger app never mutates that app's RubyLLM setup.
+      # api_base is an OpenAI-compatible-server concern and is only applied
+      # to the :openai provider.
+      def llm_context
+        RubyLLM.context do |llm|
+          llm.openai_api_base = config.api_base if provider == :openai
+          key_setter = :"#{provider}_api_key="
+          llm.public_send(key_setter, api_key) if llm.respond_to?(key_setter)
+        end
+      end
+
+      # Cascade: explicit config -> the provider's conventional env var
+      # (OPENAI_API_KEY, ANTHROPIC_API_KEY, ...) -> placeholder for keyless
+      # local servers.
+      def api_key
+        config.api_key || ENV.fetch("#{provider.to_s.upcase}_API_KEY") { PLACEHOLDER_API_KEY }
+      end
+
+      def build_prompt(events, repo)
+        lines = events.sort_by(&:timestamp).map { |e| "[#{e.timestamp}] (#{e.source}/#{e.kind}) #{e.summary}" }
+        "Repo: #{repo}\n\nActivity log, oldest to newest:\n#{lines.join("\n")}"
+      end
+
+      def parse(response)
+        data = YAML.safe_load(extract_yaml(response), permitted_classes: [Symbol]) || {}
+        build_intent(data, response)
+      rescue Psych::SyntaxError, Psych::DisallowedClass
+        build_intent({}, response)
+      end
+
+      def extract_yaml(response)
+        response[/```ya?ml\n(.*?)```/m, 1] || response
+      end
+
+      # :reek:FeatureEnvy -- this method's whole job is reading the parsed
+      # YAML hash into an Intent; that's not a sign it belongs elsewhere.
+      def build_intent(data, response)
+        Intent.new(
+          goal: data["goal"] || response.strip,
+          confidence: data["confidence"] || "unknown",
+          evidence: Array(data["evidence"]),
+          open_questions: Array(data["open_questions"]),
+          generated_at: Time.now.utc.iso8601
+        )
+      end
+
+      def empty_intent
+        Intent.new(goal: "No recent activity detected.", confidence: "low", evidence: [],
+                   open_questions: [], generated_at: Time.now.utc.iso8601)
+      end
+    end
+  end
+end

data/lib/robot_lab/am/intent.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Am
+    # The inferred goal/direction, structured per ARCHITECTURE.md's
+    # "Inference engine" section.
+    Intent = Data.define(:goal, :confidence, :evidence, :open_questions, :generated_at)
+  end
+end

data/lib/robot_lab/am/intent_writer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module RobotLab
+  module Am
+    # Writes the inferred Intent to .robot_lab_am/current_intent.md in the
+    # watched repo — front matter + prose, the same shape as robot_lab-to's
+    # decision files, under the same .robot_lab_<name>/ naming convention as
+    # robot_lab-to's own .robot_lab_to/runs/<run_id>/ run state.
+    class IntentWriter
+      def initialize(repo:)
+        @path = File.join(repo, ".robot_lab_am", "current_intent.md")
+      end
+
+      def write(intent)
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, render(intent))
+        @path
+      end
+
+      private
+
+      def render(intent)
+        front_matter = {
+          "confidence" => intent.confidence,
+          "generated_at" => intent.generated_at,
+          "evidence" => intent.evidence,
+          "open_questions" => intent.open_questions
+        }
+        "#{YAML.dump(front_matter)}---\n\n#{intent.goal}\n"
+      end
+    end
+  end
+end

data/lib/robot_lab/am/launchd.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "rbconfig"
+
+module RobotLab
+  module Am
+    # Generates and installs the per-repo launchd agent plist from
+    # ARCHITECTURE.md's Deployment model — process supervision, start on
+    # login, restart on crash. One agent per watched repo; the agent just
+    # runs `am start --foreground` and lets launchd own the process.
+    #
+    # Install/uninstall only touch the plist file; loading it into launchd is
+    # left to the user (the CLI prints the launchctl commands) so this class
+    # has no side effects beyond the file it writes.
+    class Launchd
+      LABEL_PREFIX = "com.madbomber.robot-lab-am"
+      DEFAULT_AGENTS_DIR = File.expand_path("~/Library/LaunchAgents")
+
+      def initialize(repo:, interval: nil, debounce: nil,
+                     agents_dir: DEFAULT_AGENTS_DIR, program: nil, config: nil)
+        @repo = repo
+        @interval = interval
+        @debounce = debounce
+        @agents_dir = agents_dir
+        @program = program
+        @config = config
+      end
+
+      # Repo basename plus a short path hash: readable, and unique even for
+      # two checkouts with the same basename.
+      def label
+        "#{LABEL_PREFIX}.#{File.basename(@repo)}-#{Digest::SHA256.hexdigest(@repo)[0, 8]}"
+      end
+
+      def plist_path
+        File.join(@agents_dir, "#{label}.plist")
+      end
+
+      def install
+        FileUtils.mkdir_p(@agents_dir)
+        File.write(plist_path, plist_xml)
+        plist_path
+      end
+
+      def uninstall
+        raise Error, "no launchd agent installed for #{@repo} (expected #{plist_path})" unless File.exist?(plist_path)
+
+        FileUtils.rm_f(plist_path)
+        plist_path
+      end
+
+      def plist_xml
+        log = File.join(@repo, ".robot_lab_am", "daemon.log")
+        <<~XML
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <plist version="1.0">
+          <dict>
+            <key>Label</key>
+            <string>#{xml_escape(label)}</string>
+            <key>ProgramArguments</key>
+            <array>
+          #{program_arguments.map { |arg| "    <string>#{xml_escape(arg)}</string>" }.join("\n")}
+            </array>
+            <key>WorkingDirectory</key>
+            <string>#{xml_escape(@repo)}</string>
+            <key>RunAtLoad</key>
+            <true/>
+            <key>KeepAlive</key>
+            <true/>
+            <key>StandardOutPath</key>
+            <string>#{xml_escape(log)}</string>
+            <key>StandardErrorPath</key>
+            <string>#{xml_escape(log)}</string>
+          </dict>
+          </plist>
+        XML
+      end
+
+      private
+
+      # launchd starts agents with a minimal PATH, so invoke the script with
+      # the same ruby this process is running under rather than trusting the
+      # shebang's `env ruby` to resolve.
+      def config   = @config ||= Am.config
+      def interval = @interval || config.interval
+      def debounce = @debounce || config.debounce
+
+      def program
+        @program ||= File.expand_path($PROGRAM_NAME)
+      end
+
+      # interval/debounce are baked into the plist so the launchd-run daemon
+      # behaves the same as the `am install` invocation that created it,
+      # regardless of later config-file edits.
+      def program_arguments
+        [RbConfig.ruby, program, "start", "--foreground", "--repo", @repo,
+         "--interval", interval.to_s, "--debounce", debounce.to_s]
+      end
+
+      def xml_escape(text)
+        text.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+      end
+    end
+  end
+end

data/lib/robot_lab/am/pid_file.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module RobotLab
+  module Am
+    # The daemon's pid on disk (.robot_lab_am/daemon.pid). A pid file alone
+    # can lie after a crash, which is why the daemon also writes a Heartbeat —
+    # but liveness here is still checked against the real process table
+    # (signal 0), not just the file's existence.
+    class PidFile
+      def initialize(path)
+        @path = path
+      end
+
+      def write(pid = Process.pid)
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, pid.to_s)
+      end
+
+      def read
+        return nil unless File.exist?(@path)
+
+        pid = File.read(@path).to_i
+        pid.positive? ? pid : nil
+      end
+
+      def delete
+        FileUtils.rm_f(@path)
+      end
+
+      def exist?
+        File.exist?(@path)
+      end
+
+      def alive?
+        pid = read
+        return false unless pid
+
+        Process.kill(0, pid)
+        true
+      rescue Errno::ESRCH
+        false
+      rescue Errno::EPERM
+        true
+      end
+    end
+  end
+end

data/lib/robot_lab/am/redactor.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Am
+    # Masks obvious secrets in event summaries before they reach the event
+    # store or an LLM, per ARCHITECTURE.md's Privacy & redaction section.
+    # Terminal commands and git WIP output are the risky sources (API keys in
+    # `export` statements, credentials in fixtures). Deliberately pattern-based
+    # and conservative — it catches the common shapes, not every possible leak.
+    module Redactor
+      MASK = "[REDACTED]"
+
+      # `NAME=value` / `name: value` where the name smells like a credential.
+      KEY_VALUE = /(\b[\w-]*(?:key|token|secret|password|passwd|credential)s?\b["']?\s*(?:=>|[=:])\s*["']?)([^\s"']+)/i
+
+      # `Authorization: Bearer <token>` and friends.
+      BEARER = /\b(bearer\s+)([^\s"']+)/i
+
+      # Well-known token formats that are secrets wherever they appear.
+      KNOWN_TOKEN = /
+        \b(?:
+          sk-[A-Za-z0-9_-]{16,}          # OpenAI-style
+          | AKIA[0-9A-Z]{16}             # AWS access key id
+          | gh[pousr]_[A-Za-z0-9]{20,}   # GitHub tokens
+          | github_pat_[A-Za-z0-9_]{20,} # GitHub fine-grained PAT
+          | xox[abprs]-[A-Za-z0-9-]{10,} # Slack tokens
+        )\b
+      /x
+
+      module_function
+
+      def redact_event(event)
+        event.with(summary: redact(event.summary))
+      end
+
+      def redact(text)
+        text.gsub(KEY_VALUE, "\\1#{MASK}")
+            .gsub(BEARER, "\\1#{MASK}")
+            .gsub(KNOWN_TOKEN, MASK)
+      end
+    end
+  end
+end

data/lib/robot_lab/am/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Am
+    VERSION = "0.0.1"
+  end
+end

data/lib/robot_lab/am/watchers/claude_watcher.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RobotLab
+  module Am
+    module Watchers
+      # The human's own plain-language messages from their most recent
+      # Claude Code session transcript for this repo. Richest, lowest-effort
+      # source per ARCHITECTURE.md — already on disk, no new instrumentation.
+      class ClaudeWatcher
+        PROJECTS_DIR = File.expand_path("~/.claude/projects")
+
+        def initialize(repo:, limit: 20, projects_dir: PROJECTS_DIR)
+          @repo = File.expand_path(repo)
+          @limit = limit
+          @projects_dir = projects_dir
+        end
+
+        def events
+          file = latest_transcript
+          return [] unless file
+
+          human_messages(file)
+        end
+
+        private
+
+        def latest_transcript
+          dir = project_dir
+          return nil unless dir
+
+          Dir.glob(File.join(dir, "*.jsonl")).max_by { |f| File.mtime(f) }
+        end
+
+        # Claude Code slugifies the cwd into a project directory name by
+        # replacing every non-alphanumeric character with "-". Older
+        # sessions kept underscores; fall back to a normalized match so
+        # both schemes resolve to the same repo.
+        def project_dir
+          slug  = @repo.gsub(/[^a-zA-Z0-9]/, "-")
+          exact = File.join(@projects_dir, slug)
+          return exact if Dir.exist?(exact)
+
+          normalized = slug.tr("_", "-")
+          Dir.glob(File.join(@projects_dir, "*")).find do |dir|
+            File.directory?(dir) && File.basename(dir).tr("_", "-") == normalized
+          end
+        end
+
+        def human_messages(file)
+          File.readlines(file).last(500).filter_map { |line| human_message_event(line) }.last(@limit)
+        end
+
+        # :reek:FeatureEnvy -- parsing one transcript line into an Event is
+        # inherently reading `record`/`text` more than `self`.
+        def human_message_event(line)
+          record = JSON.parse(line)
+          return nil unless record["type"] == "user"
+
+          text = extract_text(record.dig("message", "content"))
+          return nil if text.nil? || text.strip.empty?
+
+          Event.new(timestamp: record["timestamp"], repo: @repo, source: "claude_code",
+                    kind: "user_message", summary: text.strip[0, 500])
+        rescue JSON::ParserError
+          nil
+        end
+
+        # Only plain text blocks count as "the human said something" — this
+        # skips synthetic user turns that are actually tool_result payloads.
+        def extract_text(content)
+          return content if content.is_a?(String)
+          return nil unless content.is_a?(Array)
+
+          blocks = content.select { |block| block["type"] == "text" }
+          return nil if blocks.empty?
+
+          blocks.map { |block| block["text"] }.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/am/watchers/git_watcher.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module RobotLab
+  module Am
+    module Watchers
+      # Recent commits plus current uncommitted state, for one repo.
+      # All subprocess calls use explicit argv arrays (no shell interpolation).
+      class GitWatcher
+        GIT_ENV = { "GIT_TERMINAL_PROMPT" => "0" }.freeze
+        LOG_FORMAT = "%H%x09%aI%x09%s"
+
+        def initialize(repo:, limit: 20)
+          @repo = repo
+          @limit = limit
+        end
+
+        def events
+          commit_events + wip_events
+        end
+
+        private
+
+        def commit_events
+          out, _err, status = Open3.capture3(
+            GIT_ENV, "git", "log", "-n", @limit.to_s, "--format=#{LOG_FORMAT}", chdir: @repo
+          )
+          return [] unless status.success?
+
+          out.each_line.filter_map { |line| commit_event(line) }
+        end
+
+        def commit_event(line)
+          sha, iso_time, subject = line.chomp.split("\t", 3)
+          return nil unless sha && iso_time
+
+          Event.new(timestamp: iso_time, repo: @repo, source: "git", kind: "commit",
+                    summary: "#{sha[0, 7]} #{subject}")
+        end
+
+        def wip_events
+          out, _err, status = Open3.capture3(GIT_ENV, "git", "status", "--short", chdir: @repo)
+          return [] unless status.success?
+
+          # This gem's own state dir is not the human's work — reporting it
+          # would make the daemon observe (and infer over) its own footprint.
+          lines = out.lines.map(&:chomp).reject { |line| line.empty? || line.include?(".robot_lab_am") }
+          return [] if lines.empty?
+
+          [Event.new(timestamp: Time.now.utc.iso8601, repo: @repo, source: "git", kind: "wip",
+                     summary: "Uncommitted changes:\n#{lines.join("\n")}")]
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/am/watchers/terminal_watcher.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Am
+    module Watchers
+      # Commands run in the repo, read from the global preexec log written
+      # by ~/.bashrc__activity_monitor. That log spans every shell on the
+      # machine (see ARCHITECTURE.md's Privacy & redaction section) — the
+      # opt-in boundary is enforced here, at read time, by filtering to
+      # lines whose cwd falls under this one watched repo root.
+      class TerminalWatcher
+        DEFAULT_LOG_PATH = File.expand_path("~/.activity_monitor/terminal_activity.log")
+
+        def initialize(repo:, log_path: DEFAULT_LOG_PATH, limit: 50)
+          @repo = File.expand_path(repo)
+          @log_path = log_path
+          @limit = limit
+        end
+
+        def events
+          return [] unless File.exist?(@log_path)
+
+          File.readlines(@log_path).filter_map { |line| command_event(line) }.last(@limit)
+        end
+
+        private
+
+        def command_event(line)
+          epoch, cwd, command = line.chomp.split("\t", 3)
+          return nil unless epoch && cwd && command && in_scope?(cwd)
+
+          Event.new(timestamp: Time.at(epoch.to_f).utc.iso8601, repo: @repo, source: "terminal",
+                    kind: "command", summary: command)
+        end
+
+        def in_scope?(cwd)
+          cwd == @repo || cwd.start_with?("#{@repo}/")
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/am.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "am/version"
+require_relative "am/config"
+require_relative "am/event"
+require_relative "am/event_log"
+require_relative "am/redactor"
+require_relative "am/intent"
+require_relative "am/inferrer"
+require_relative "am/intent_writer"
+require_relative "am/watchers/git_watcher"
+require_relative "am/watchers/claude_watcher"
+require_relative "am/watchers/terminal_watcher"
+require_relative "am/collector"
+require_relative "am/pid_file"
+require_relative "am/heartbeat"
+require_relative "am/daemon"
+require_relative "am/daemon_controller"
+require_relative "am/launchd"
+require_relative "am/cli"
+
+module RobotLab
+  module Am
+    class Error < StandardError; end
+
+    class << self
+      # Process-wide Config (defaults.yml -> user config file ->
+      # RLAM_* env vars). Components use it for any setting not
+      # passed to them explicitly.
+      def config
+        @config ||= Config.new
+      end
+
+      # Test hook: drop the memoized config so changed env vars are re-read.
+      def reset_config!
+        @config = nil
+      end
+    end
+  end
+end