maf 0.1.0

data/assets/dashboard

@@ -0,0 +1,553 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# dashboard - local observability web UI for multi-agent coordination.
+#
+# Usage: dashboard [--port N] [--coord DIR] [--interval S]
+#
+# Starts a local HTTP server at http://localhost:4567 (default).
+# The page auto-refreshes every S seconds (default: 5).
+# Run from the project root where .maf/coordination/ lives.
+#
+# >>> multi-agent-flow >>>
+# <<< multi-agent-flow <<<
+
+require "json"
+require "fileutils"
+require "time"
+require "optparse"
+require "rbconfig"
+require "securerandom"
+begin
+  require_relative "../lib/maf/shared/processes"
+  require_relative "../lib/maf/shared/peak_rate"
+rescue LoadError
+  abort "dashboard: the maf shared library is missing. Run maf update."
+end
+begin
+  require "webrick"
+rescue LoadError
+  abort "dashboard: webrick is required. Install it with: gem install webrick"
+end
+
+abort "dashboard: Ruby 3.0+ required (current: #{RUBY_VERSION})." if RUBY_VERSION.split(".").first.to_i < 3
+
+module Dashboard
+  DEFAULT_PORT     = 4567
+  DEFAULT_INTERVAL = 5
+  DEFAULT_COORD    = ".maf/coordination"
+  DEFAULT_LEASE    = 4 * 3600
+
+  class Config
+    attr_reader :port, :coord_dir, :interval, :maf
+
+    # Each flag: the OptionParser arguments and the instance variable it sets.
+    FLAGS = { ["--port N", Integer] => :@port, ["--coord DIR"] => :@coord_dir,
+              ["--interval S", Integer] => :@interval, ["--maf PATH"] => :@maf }.freeze
+
+    def initialize(argv)
+      @port, @coord_dir, @interval, @maf = DEFAULT_PORT, DEFAULT_COORD, DEFAULT_INTERVAL, "maf"
+      parser = OptionParser.new
+      FLAGS.each { |args, name| parser.on(*args) { |value| instance_variable_set(name, value) } }
+      parser.parse!(argv)
+    end
+
+    def taskrc       = File.join(coord_dir, "taskrc")
+    def log_path     = File.join(coord_dir, "events.log")
+    def inbox_dir    = File.join(coord_dir, "inbox")
+    def locks_dir    = File.join(coord_dir, "locks")
+    def manifest     = File.join(File.dirname(coord_dir), "config.json")
+    def workers_path = File.join(coord_dir, "workers.json")
+    def vault_path   = File.join(File.dirname(File.expand_path(coord_dir)), "bin", "vault")
+    def analyst_path = File.join(File.dirname(File.expand_path(coord_dir)), "bin", "analyst")
+    def root         = File.dirname(File.dirname(File.expand_path(coord_dir)))
+    def lease_ttl
+      v = Integer(ENV.fetch("COORD_LEASE_TTL", ""), exception: false)
+      v&.positive? ? v : DEFAULT_LEASE
+    end
+  end
+
+  class TaskReader
+    def initialize(taskrc)
+      @taskrc = taskrc
+    end
+
+    QUERY = ["task", "(", "status:pending", "or", "status:waiting", ")", "export"].freeze
+
+    def read
+      return [] unless File.exist?(@taskrc)
+
+      IO.popen(ENV.to_h.merge("TASKRC" => @taskrc), QUERY, err: File::NULL) { |f| parse(f.read) }
+    rescue StandardError
+      []
+    end
+
+    private
+
+    def parse(raw)
+      raw.strip.empty? ? [] : JSON.parse(raw)
+    rescue JSON::ParserError
+      []
+    end
+  end
+
+# GraphReader asks `vault age --json` for the graph age. An absent vault
+# script or a failure gives nil.
+class GraphReader
+  def initialize(cfg)
+    @cfg = cfg
+  end
+
+  def read
+    JSON.parse(IO.popen([RbConfig.ruby, @cfg.vault_path, "age", "--json"], chdir: @cfg.root, err: File::NULL, &:read))
+  rescue SystemCallError, JSON::ParserError
+    nil
+  end
+end
+
+  # WorkerReader puts every fact about one worker in one record: the registry
+  # entry (.maf/coordination/workers.json), presence, the status that the
+  # dispatcher or the context-watch hook writes, token usage, the last log
+  # lines, and the result of the last dashboard action.
+  class WorkerReader
+    LOG_LINES = 5
+    HISTORY = 20
+
+    # last_events maps each worker to the time of its last event.
+    def initialize(cfg, last_events = {})
+      @cfg = cfg
+      @last_events = last_events
+    end
+
+    def read(id, entry)
+      entry.merge("id" => id, "live" => live?(file("presence", id)), "status" => file("status", id),
+                  "usage" => file("usage", id), "log" => tail("#{id}.log"), "action" => tail("#{id}.control.log"),
+                  "handoff_at" => mtime(File.join(sessions, "#{id}.handoff.md")), "last_event" => @last_events[id],
+                  "runs" => history(id), "analysis" => file("hints", id))
+    end
+
+    private
+
+    def sessions = File.join(@cfg.coord_dir, "sessions")
+
+    def file(dir, id)
+      path = File.join(@cfg.coord_dir, dir, "#{id}.json")
+      File.exist?(path) ? JSON.parse(File.read(path)) : {}
+    rescue JSON::ParserError
+      {}
+    end
+
+    # A pid can belong to a new process. The recorded start time tells them apart.
+    def live?(presence)
+      pid = presence["pid"].to_i
+      Maf::Shared::Processes.alive?(pid) && [nil, "", Maf::Shared::Processes.started_at(pid)].include?(presence["started"])
+    end
+
+    def tail(name)
+      path = File.join(sessions, name)
+      File.exist?(path) ? File.readlines(path).last(LOG_LINES).map(&:chomp) : []
+    end
+
+    def mtime(path) = File.exist?(path) ? File.mtime(path).utc.iso8601 : nil
+
+    # The dispatcher appends one line per run. A broken line counts as no run.
+    def history(id)
+      path = File.join(@cfg.coord_dir, "usage", "#{id}.runs.jsonl")
+      lines = File.exist?(path) ? File.readlines(path).last(HISTORY) : []
+      lines.filter_map { |line| JSON.parse(line) rescue nil }
+    end
+  end
+
+  # ActionRunner runs `maf worker ACTION ID` in the background. A stop can
+  # wait for a running agent, so the request does not wait for the command.
+  # The output goes to sessions/<id>.control.log, which the page shows.
+  class ActionRunner
+    ACTIONS = %w[start stop restart analyze].freeze
+
+    def initialize(cfg)
+      @cfg = cfg
+    end
+
+    LIMITS = %w[max_context max_session_runs cache_window].freeze
+
+    # Returns an error text, or nil when the command started. limits are the
+    # session limits that a restart saves (see TokenHints).
+    def run(id, action, limits = {})
+      return "unknown action #{action}" unless ACTIONS.include?(action)
+      return "unknown worker #{id}" unless registered?(id)
+      return "unknown limit" unless limits.all? { |key, value| LIMITS.include?(key) && value.is_a?(Integer) }
+
+      return spawn_analyst(id) if action == "analyze"
+
+      spawn_maf(id, action, limits.flat_map { |key, value| ["--#{key.tr("_", "-")}", value.to_s] })
+    end
+
+    private
+
+    def start_log(id, action)
+      log = File.join(@cfg.coord_dir, "sessions", "#{id}.control.log")
+      FileUtils.mkdir_p(File.dirname(log))
+      File.write(log, "[#{Time.now.utc.iso8601}] #{action} #{id}\n", mode: "a")
+      log
+    end
+
+    def registered?(id)
+      JSON.parse(File.read(@cfg.workers_path)).key?(id)
+    rescue Errno::ENOENT, JSON::ParserError
+      false
+    end
+
+    # The analyst asks a small model for hints. It writes hints/<id>.json.
+    def spawn_analyst(id)
+      log = start_log(id, "analyst")
+      pid = spawn(RbConfig.ruby, @cfg.analyst_path, id, "--coord", File.expand_path(@cfg.coord_dir),
+                  chdir: @cfg.root, in: File::NULL, out: [log, "a"], err: %i[child out])
+      Process.detach(pid) && nil
+    rescue SystemCallError => e
+      "analyst did not start: #{e.message}. Run maf update."
+    end
+
+    def spawn_maf(id, action, flags)
+      log = start_log(id, ["maf worker", action, *flags].join(" "))
+      pid = spawn(@cfg.maf, "worker", action, id, *flags, chdir: @cfg.root, in: File::NULL, out: [log, "a"],
+                  err: %i[child out])
+      Process.detach(pid) && nil
+    rescue SystemCallError => e
+      "maf did not start: #{e.message}. Put maf on PATH or pass --maf PATH."
+    end
+  end
+
+  # TokenHints reads the run history of a dispatched worker and suggests
+  # better session limits. The page shows each hint with a button that
+  # restarts the worker with the suggested limit. Only the runs with the
+  # limits of the last run count, so a restart with new limits clears the
+  # hints of the old limits. assets/dispatcher writes the history (RunHistory).
+  class TokenHints
+    RATIO = 3
+    MIN_RUNS = 2
+    COLD_WRITE = 0.25
+    MIN_CONTEXT = 40_000
+
+    def initialize(worker, now = Time.now.utc)
+      @id, @now = worker["id"], now
+      runs = worker["runs"] || []
+      @runs = runs.select { |run| run["limits"] == runs.last["limits"] }
+    end
+
+    def list = @runs.empty? ? [] : [growth, cold, peak].compact
+
+    private
+
+    def fresh = @runs.select { |run| run["session_run"] == 1 }
+    def resumed = @runs.reject { |run| run["session_run"] == 1 }
+    def limits = @runs.last["limits"] || {}
+    def median(runs, key) = runs.map { |run| run[key].to_i }.sort[runs.size / 2]
+    def hint(level, text, limits = nil) = { worker: @id, level: level, text: text, limits: limits }.compact
+
+    # Each resume sends the old context again, so a long session costs more per run.
+    def growth
+      return unless fresh.any? && resumed.size >= MIN_RUNS && ratio >= RATIO
+
+      @runs.any? { |run| run["context"] } ? context_cap : fresh_runs
+    end
+
+    def ratio = median(resumed, "input_tokens").fdiv([median(fresh, "input_tokens"), 1].max)
+
+    def growth_text
+      "#{@id}: a resumed run uses #{ratio.round(1)}x the input of a fresh run " \
+        "(#{tokens(median(resumed, "input_tokens"))} vs #{tokens(median(fresh, "input_tokens"))})."
+    end
+
+    def context_cap
+      cap = [(median(fresh, "context") * 2 / 10_000.0).ceil * 10_000, MIN_CONTEXT].max
+      return if limits["max_context"].to_i.positive? && limits["max_context"] <= cap
+
+      hint("warn", "#{growth_text} Cap the session context at #{cap / 1000}k tokens.", "max_context" => cap)
+    end
+
+    def fresh_runs
+      return if limits["max_session_runs"] == 1
+
+      hint("warn", "#{growth_text} Start each run fresh with the handoff note.", "max_session_runs" => 1)
+    end
+
+    # A large cache write on a resume means that the cache expired first.
+    def cold
+      runs = resumed.select { |run| run["cache_write_input_tokens"].to_i > COLD_WRITE * run["input_tokens"].to_i }
+      window = limits["cache_window"].to_i / 2
+      return if runs.size < MIN_RUNS || window < 60
+
+      hint("warn", "#{@id}: #{runs.size} resumed runs found a cold cache. Lower the cache window to #{window} s.",
+           "cache_window" => window)
+    end
+
+    def peak
+      hours = Maf::Shared::PeakRate.hours(@now)
+      return unless @runs.last["peak"] && hours
+
+      hint("info", "#{@id}: DeepSeek runs cost 2x the off-peak rate until #{hours.end}:00 UTC. " \
+                   "Stop the worker to wait for the off-peak rate.").merge(action: "stop")
+    end
+
+    def tokens(count) = count >= 1_000_000 ? "#{(count / 1e6).round(1)}M" : "#{(count / 1e3).round}k"
+  end
+
+  # Collector builds the data of one page refresh.
+  class Collector
+    def initialize(cfg)
+      @cfg = cfg
+      @files = BoardFiles.new(cfg)
+    end
+
+    def collect
+      { project: File.basename(Dir.pwd), generated_at: Time.now.utc.iso8601, refresh_interval: @cfg.interval,
+        lease_ttl: @cfg.lease_ttl, declared_roles: declared_roles }.merge(board)
+    end
+
+    private
+
+    def board
+      tasks = TaskReader.new(@cfg.taskrc).read
+      list = workers
+      { workers: list, hints: list.flat_map { |worker| TokenHints.new(worker).list + analysis(worker) },
+        graph: GraphReader.new(@cfg).read, tasks: TaskSummary.new(@cfg, declared_roles).of(tasks),
+        events: @files.recent_events, inboxes: @files.inbox_messages, locks: @files.active_locks }
+    end
+
+    # The analyst writes running, then its hints or its error.
+    def analysis(worker)
+      data = worker["analysis"] || {}
+      base = { worker: worker["id"], level: "analysis", at: data["at"] }
+      return [base.merge(text: "#{worker["id"]}: the analyst runs.")] if data["running"]
+      return [base.merge(text: "#{worker["id"]}: the analyst failed: #{data["error"]}")] if data["error"]
+
+      Array(data["hints"]).map { |hint| base.merge(text: "#{worker["id"]}: #{hint["text"]}", limits: hint["limits"]) }
+    end
+
+    def declared_roles
+      JSON.parse(File.read(@cfg.manifest)).fetch("agents", []).map { |entry| entry["role"] }.compact
+    rescue Errno::ENOENT, JSON::ParserError
+      []
+    end
+
+    # .maf/coordination/workers.json lists each worker that `maf prepare` or
+    # `maf start` set up. The last event shows when the worker last acted.
+    def workers
+      reader = WorkerReader.new(@cfg, @files.recent_events(500).to_h { |event| [event[:worker], event[:ts]] })
+      JSON.parse(File.read(@cfg.workers_path)).map { |id, entry| reader.read(id, entry) }
+    rescue Errno::ENOENT, JSON::ParserError
+      []
+    end
+  end
+
+  # TaskSummary sorts the pending tasks into the lists that raise alerts.
+  class TaskSummary
+    def initialize(cfg, roles)
+      @cfg = cfg
+      @roles = roles
+    end
+
+    def of(tasks)
+      { all: tasks, stale: tasks.select { |t| stale?(t) }, orphaned: orphaned(tasks),
+        conflicts: scope_conflicts(tasks), escalated: tasks.select { |t| note?(t, "ESCALATED:") },
+        in_review: tasks.select { |t| t["role"] == "goal" && note?(t, "PR:") } }
+    end
+
+    private
+
+    # `coord escalate --task` writes an ESCALATED note. `coord goal pr` writes
+    # a PR note on the goal. A done task leaves the pending list.
+    def note?(task, prefix) = (task["annotations"] || []).any? { |note| note["description"].to_s.start_with?(prefix) }
+
+    def stale?(task)
+      start = task["start"].to_s
+      !start.empty? && Time.parse(start) + @cfg.lease_ttl <= Time.now
+    rescue ArgumentError
+      false
+    end
+
+    # Goals are not work for a role, so a goal never lacks a runner.
+    def orphaned(tasks)
+      return [] if @roles.empty?
+
+      tasks.select { |t| t["role"] && t["role"] != "goal" && !@roles.include?(t["role"]) }
+    end
+
+    def scope_conflicts(tasks)
+      tasks.combination(2).select { |a, b| overlap?(a["scope"], b["scope"]) }.map { |a, b| [a["uuid"], b["uuid"]] }
+    end
+
+    def overlap?(first, second)
+      short, long = [parts(first), parts(second)].sort_by(&:size)
+      !short.empty? && short == long.first(short.size)
+    end
+
+    def parts(scope) = scope.to_s.split("/").take_while { |part| part !~ /[*?{}]/ }
+  end
+
+  # BoardFiles reads the event log, the inboxes, and the locks.
+  class BoardFiles
+    def initialize(cfg)
+      @cfg = cfg
+    end
+
+    def recent_events(limit = 60)
+      path = @cfg.log_path
+      File.exist?(path) ? File.readlines(path).last(limit).filter_map { |line| parse_event(line.chomp) } : []
+    end
+
+    def inbox_messages
+      roles = Dir.exist?(@cfg.inbox_dir) ? Dir.children(@cfg.inbox_dir) : []
+      roles.select { |role| File.directory?(File.join(@cfg.inbox_dir, role)) }.to_h { |role| [role, messages(role)] }
+    end
+
+    def active_locks = Dir.glob(File.join(@cfg.locks_dir, "*.json")).filter_map { |path| read_lock(path) }
+
+    private
+
+    def parse_event(line)
+      ts, action, worker, detail = line.split("\t", 4)
+      ts && action ? { ts: ts, action: action, worker: worker, detail: detail } : nil
+    end
+
+    def messages(role) = Dir.glob(File.join(@cfg.inbox_dir, role, "*.md")).sort.filter_map { |p| read_message(p) }
+
+    def read_message(path)
+      header, body = File.read(path).split("\n\n", 2)
+      { from: header[/^# from: (.+)$/, 1], at: header[/^# at: (.+)$/, 1], preview: body.to_s.strip.slice(0, 140) }
+    rescue Errno::ENOENT
+      nil
+    end
+
+    # A lock without a ttl is a mutex of `coord with-lock`. Only advisory locks expire.
+    def read_lock(meta)
+      data = JSON.parse(File.read(meta))
+      ts, ttl = data["ts"].to_i, data["ttl"].to_i
+      ttl.positive? ? lock_record(File.basename(meta, ".json"), data["worker"], ts, ttl) : nil
+    rescue JSON::ParserError, Errno::ENOENT
+      nil
+    end
+
+    def lock_record(name, worker, ts, ttl)
+      { name: name, worker: worker, acquired_at: Time.at(ts).utc.iso8601,
+        expires_at: Time.at(ts + ttl).utc.iso8601, stale: ts + ttl < Time.now.to_i }
+    end
+  end
+
+  # Page reads the HTML page. It lives next to this script: the installer copies both.
+  module Page
+    PATH = File.join(__dir__, "dashboard.html")
+
+    def self.html
+      File.read(PATH)
+    rescue Errno::ENOENT
+      abort "dashboard: #{PATH} is missing. Run maf update."
+    end
+  end
+
+  # BoardCheck finds out if the coordination folder exists. The default folder
+  # is relative, so a wrong working directory gives an empty page without it.
+  class BoardCheck
+    def initialize(cfg)
+      @cfg = cfg
+    end
+
+    # Returns an error text, or nil if the task board exists.
+    def problem
+      return nil if File.exist?(@cfg.taskrc)
+      "no task board at #{File.expand_path(@cfg.coord_dir)}.\n" \
+        "Run dashboard from the project root, or pass --coord DIR.#{old_layout_hint}"
+    end
+
+    private
+
+    def old_layout_hint
+      File.exist?("coordination/taskrc") ? "\nThis project uses the old layout. Run: maf migrate" : ""
+    end
+  end
+
+  # Server serves the page, the data, and the worker actions. An action needs
+  # the token of this server run, which only the page knows, and a localhost
+  # Host header. So another web site in the browser cannot start an action.
+  class Server
+    def initialize(cfg)
+      @cfg       = cfg
+      @collector = Collector.new(cfg)
+      @actions   = ActionRunner.new(cfg)
+      @token     = SecureRandom.hex(16)
+      @page      = Page.html
+    end
+
+    def run
+      BoardCheck.new(@cfg).problem&.then { |problem| abort "dashboard: #{problem}" }
+      server = mount(build_server)
+      trap("INT") { server.shutdown }
+      puts "dashboard: http://localhost:#{@cfg.port}  (ctrl-c to stop)"
+      server.start
+    end
+
+    private
+
+    def mount(server)
+      server.mount_proc("/")     { |req, res| local(req, res) { html(res) } }
+      server.mount_proc("/data") { |req, res| local(req, res) { json(res) } }
+      server.mount_proc("/action") { |req, res| action(req, res) }
+      server
+    end
+
+    def build_server
+      WEBrick::HTTPServer.new(BindAddress: "127.0.0.1",
+                              Port: @cfg.port,
+                              Logger: WEBrick::Log.new(File::NULL),
+                              AccessLog: [])
+    end
+
+    def html(res)
+      res.content_type = "text/html; charset=utf-8"
+      res.body = @page.sub("__TOKEN__", @token)
+    end
+
+    def action(req, res)
+      error = refusal(req) || run_action(JSON.parse(req.body.to_s))
+      answer(res, error ? 400 : 202, error ? { error: error } : { ok: true })
+    rescue JSON::ParserError
+      answer(res, 400, error: "the body is not JSON")
+    end
+
+    def run_action(body)
+      limits = body["limits"].is_a?(Hash) ? body["limits"] : {}
+      @actions.run(body["worker"].to_s, body["action"].to_s, limits)
+    end
+
+    def answer(res, status, data)
+      res.content_type = "application/json"
+      res.status = status
+      res.body = JSON.generate(data)
+    end
+
+    def refusal(req)
+      return "use POST" unless req.request_method == "POST"
+      return "wrong token" unless req["X-Maf-Token"] == @token
+
+      "wrong host" unless local_host?(req)
+    end
+
+    # DNS rebinding points a foreign name at 127.0.0.1. The Host header still
+    # names the foreign site, so the page and the board data stay private.
+    def local(req, res)
+      return yield if local_host?(req)
+
+      res.status = 403
+      res.body = "wrong host"
+    end
+
+    def local_host?(req) = req.host.to_s.match?(/\A(localhost|127\.0\.0\.1)\z/)
+
+    def json(res)
+      res.content_type = "application/json"
+      res.body = JSON.generate(@collector.collect)
+    end
+  end
+end
+
+Dashboard::Server.new(Dashboard::Config.new(ARGV)).run if __FILE__ == $PROGRAM_NAME