maf 0.1.0 → 0.2.0

data/lib/maf/setup_agent/launcher.rb

@@ -1,21 +1,22 @@
 # frozen_string_literal: true
 
+require_relative "../shared/sandbox"
+require_relative "pty_relay"
+
 module Maf
   module SetupAgent
+    # Launcher replaces this process with the interactive session of a harness.
+    # The harness file builds the command (Maf::Shared::Harnesses).
     module Launcher
-      REGISTRY = {}
+      def self.launch(harness, role, model)
+        ENV.update(harness.launch_env)
+        return exec_or_die(harness.launch(role, model)) if Maf::Shared::Sandbox.mode == "off"
 
-      def self.for(harness)
-        register_defaults if REGISTRY.empty?
-        REGISTRY.fetch(harness) { abort "setup_agent: no launcher for harness '#{harness}' yet." }
+        warn "maf: sandbox: #{Maf::Shared::Sandbox.describe(harness)}"
+        exit Maf::Shared::Sandbox.keeping_links(harness) { relay_or_die(sandboxed(harness, role, model)) }
       end
 
-      def self.register_defaults
-        REGISTRY["claude"] = Claude
-        REGISTRY["opencode"] = Opencode
-        REGISTRY["codex"] = Codex
-        REGISTRY["hermes"] = Hermes
-      end
+      def self.sandboxed(harness, role, model) = Maf::Shared::Sandbox.wrap(harness.launch(role, model), harness)
 
       def self.exec_or_die(cmd)
         Kernel.exec(*cmd)
@@ -23,62 +24,10 @@ module Maf
         abort "setup_agent: '#{cmd.first}' not found on PATH."
       end
 
-      # FlowFiles finds the files of the flow in .maf/ of the main project. The
-      # project's own harness config stays as it is: each file of the flow is
-      # passed to the harness at the start.
-      module FlowFiles
-        def self.path(*parts) = File.join(Project.root, ".maf", *parts)
-        def self.flag(name, *parts) = File.exist?(path(*parts)) ? [name, path(*parts)] : []
-      end
-
-      # --settings adds the hooks of the flow, --mcp-config adds the graph server.
-      # --mcp-config takes many values, so `--` ends the options before the prompt.
-      module Claude
-        def self.launch(role, _worker, model)
-          prompt = "Read .maf/agents/claude/#{role}.md and follow it exactly. Start your work loop now."
-          cmd = ["claude", *FlowFiles.flag("--settings", "claude", "settings.json"),
-                 *FlowFiles.flag("--mcp-config", "mcp", "claude.json")]
-          Launcher.exec_or_die(cmd + (model ? ["--model", model] : []) + ["--", prompt])
-        end
-      end
-
-      # opencode merges the file in OPENCODE_CONFIG with the project's opencode.json.
-      module Opencode
-        def self.launch(role, _worker, model)
-          config = FlowFiles.path("mcp", "opencode.json")
-          ENV["OPENCODE_CONFIG"] = config if File.exist?(config)
-          cmd = ["opencode", ".", "--agent", role, "--prompt", "Start your work loop now."]
-          Launcher.exec_or_die(cmd + (model ? ["--model", model] : []))
-        end
-      end
-
-      module Codex
-        def self.launch(role, _worker, model)
-          prompt_file = ".codex/prompts/#{role}.md"
-          abort "setup_agent: #{prompt_file} missing." unless File.exist?(prompt_file)
-
-          cmd = ["codex", *writable_dirs]
-          cmd += ["--model", model] if model
-          warn_untrusted
-          Launcher.exec_or_die(cmd + [File.read(prompt_file)])
-        end
-
-        UNTRUSTED = "maf: Codex does not trust the hooks in %<file>s yet. Trust them when Codex asks. " \
-                    "Without the hooks, the session records no token usage, and coord await cannot wake it."
-
-        # Codex runs the hooks of a project only after the user trusts them, and
-        # a worktree is a new project for Codex. Codex records the trust in its config.toml.
-        def self.warn_untrusted
-          hooks = File.join(File.realpath(Dir.pwd), ".codex", "hooks.json")
-          config = File.join(ENV.fetch("CODEX_HOME", File.join(Dir.home, ".codex")), "config.toml")
-          trusted = File.exist?(config) && File.read(config).include?("#{hooks}:stop:")
-          warn format(UNTRUSTED, file: hooks) if File.exist?(hooks) && !trusted
-        end
-
-        # The worktree is the only writable root of the Codex sandbox. coord
-        # writes the board and the artifacts in .maf/coordination of the main
-        # project, so Codex would ask for approval at each coord command.
-        def self.writable_dirs = ["--add-dir", File.join(SetupAgent::Project.root, ".maf", "coordination")]
+      def self.relay_or_die(cmd)
+        PtyRelay.new(cmd).run
+      rescue Errno::ENOENT
+        abort "setup_agent: '#{cmd.first}' not found on PATH."
       end
     end
   end

data/lib/maf/setup_agent/pty_relay.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "pty"
+require "io/console"
+
+module Maf
+  module SetupAgent
+    # PtyRelay runs a command on its own pseudo terminal and copies the input and the output.
+    class PtyRelay
+      CHUNK = 4096
+      DRAIN = 0.5
+      SIGNALS = %w[TERM HUP INT].freeze
+      EOF = "\x04"
+
+      def initialize(cmd) = @cmd = cmd
+
+      def run
+        output, input, pid = PTY.spawn(*@cmd)
+        SIGNALS.each { |name| Signal.trap(name) { pass(name, pid) } }
+        relay(output, input, Process.detach(pid))
+      ensure
+        [output, input].compact.each(&:close)
+      end
+
+      private
+
+      def relay(output, input, waiter)
+        resize(input) && Signal.trap("WINCH") { resize(input) }
+        copiers = [Thread.new { copy_input(input) }, Thread.new { copy(output, $stdout) }]
+        raw { waiter.join }
+        stop(copiers)
+        waiter.value.exitstatus || 1
+      end
+
+      def stop(copiers)
+        copiers.last.join(DRAIN)
+        copiers.each(&:kill)
+      end
+
+      def copy(from, to)
+        loop { to.write(from.readpartial(CHUNK)) && to.flush }
+      rescue IOError, Errno::EIO
+        nil
+      end
+
+      # The end of the input is no end on a terminal, so the command gets ^D. Else `echo task | maf start` waits.
+      # After a line without a newline, the first ^D only sends the line, so the command gets a second one.
+      def copy_input(input)
+        last = send_input(input)
+        input.write(last.end_with?("\n") ? EOF : EOF * 2)
+      rescue IOError, Errno::EIO
+        nil
+      end
+
+      def send_input(input)
+        last = "\n"
+        loop { input.write(last = $stdin.readpartial(CHUNK)) && input.flush }
+      rescue EOFError
+        last
+      end
+
+      def pass(name, pid)
+        Process.kill(name, pid)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      def raw(&block) = $stdin.tty? ? $stdin.raw(&block) : yield
+
+      def resize(input)
+        $stdout.tty? && (input.winsize = $stdout.winsize)
+      end
+    end
+  end
+end

data/lib/maf/setup_agent/role_file.rb

@@ -8,7 +8,7 @@ module Maf
     # A harness folder with the project's own files gets one link per role file.
     module RoleFile
       def self.copy(root, dir, harness, role)
-        relative = Flow.role_path(harness, role)
+        relative = Maf::Shared::Harness.fetch(harness).role_path(role)
         return unless relative
 
         copy_missing(File.join(root, relative), File.join(dir, relative))

data/lib/maf/setup_agent/runtime_hooks.rb

@@ -8,18 +8,7 @@ module Maf
     module RuntimeHooks
       def self.install(dir, harness)
         %w[next-task.rb board-watch.rb session-guard.rb context-watch.rb].each { |name| copy(dir, name) }
-        configure(dir, harness)
-        copy(dir, "board-watch-opencode.js", ".opencode/plugins/board-watch.js") if harness == "opencode"
-      end
-
-      # Claude Code reads the hooks from the settings file of the main project
-      # (`maf start` passes it with --settings). The hook commands run in the
-      # worktree, where the copies above live.
-      def self.configure(dir, harness)
-        root = Project.root
-        settings = File.join(root, Bootstrap::CLAUDE_SETTINGS)
-        Bootstrap::ClaudeSettings.new(Bootstrap::Project.new(root, false)).configure(settings) if harness == "claude"
-        Flow::CodexHooks.new(dir).install if harness == "codex"
+        Maf::Shared::Harness.fetch(harness).runtime_hooks(dir)
       end
 
       def self.copy(dir, name, relative = ".maf/coordination/harness-hooks/#{name}")

data/lib/maf/setup_agent.rb

@@ -85,7 +85,7 @@ module Maf
       return Dispatch.launch(args, model) if args.dispatch
 
       MafSession.register(Project.root, args.harness)
-      Launcher.for(args.harness).launch(args.role, args.worker, model)
+      Launcher.launch(Maf::Shared::Harness.fetch(args.harness), args.role, model)
     end
 
     # The session and the dispatcher pass the environment to each child, so
@@ -104,8 +104,6 @@ require_relative "setup_agent/role_file"
 require_relative "setup_agent/manifest"
 require_relative "setup_agent/worktree"
 require_relative "setup_agent/launcher"
-require_relative "setup_agent/hermes_launcher"
 require_relative "setup_agent/project"
-require_relative "setup_agent/hermes_skill"
 require_relative "setup_agent/runtime_hooks"
 require_relative "../../assets/harness-hooks/session-guard"

data/lib/maf/shared/harness/base.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# maf shared library - code that the maf CLI and the scripts in .maf/bin share.
+# The installer copies this folder to .maf/lib/maf/shared/. maf update replaces it.
+# Use the Ruby stdlib only: a script loads this file without a gem bundle.
+require "erb"
+require "json"
+require_relative "defaults"
+require_relative "output"
+
+module Maf
+  module Shared
+    # Harness is the registry of the agent harnesses. Each file in harnesses/
+    # defines one harness: a subclass of Base. The rest of maf asks the
+    # registry and never names a harness.
+    module Harness
+      def self.register(klass) = (@classes ||= []) << klass
+      def self.all = @all ||= @classes.map(&:new).sort_by(&:name)
+      def self.names = all.map(&:name)
+      def self.[](name) = all.find { |harness| harness.name == name }
+      def self.fetch(name) = self[name] || raise(KeyError, "unknown harness '#{name}' (use #{names.join(", ")})")
+      def self.known?(name) = !self[name].nil?
+
+      def self.on_path?(command)
+        ENV["PATH"].to_s.split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, command)) }
+      end
+
+      # Base is the interface of a harness. A harness file overrides the
+      # methods that its CLI needs. Every other method keeps the default here.
+      # The methods are grouped by the part of maf that calls them.
+      class Base
+        def self.inherited(klass)
+          super
+          Harness.register(klass)
+        end
+
+        # The harness name in `maf add HARNESS:ROLE`. It comes from the class name.
+        def name = self.class.name.split("::").last.downcase
+        def to_s = name
+
+        # The CLI of the harness. `maf add` offers only the installed harnesses.
+        def command = name
+        def installed? = Harness.on_path?(command)
+
+        include RoleFiles
+        include Setup
+        include Run
+
+        # The tool calls of one session, for the analyst: [[name, command, size], ...].
+        def transcript_calls(_session_id) = []
+
+        # The JSON objects of a transcript file, one per line. A broken line is skipped.
+        def jsonl(path) = path ? File.foreach(path).filter_map { |line| Events.parse(line.strip) } : []
+      end
+    end
+  end
+end

data/lib/maf/shared/harness/defaults.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+# maf shared library - code that the maf CLI and the scripts in .maf/bin share.
+# The installer copies this folder to .maf/lib/maf/shared/. maf update replaces it.
+# Use the Ruby stdlib only: a script loads this file without a gem bundle.
+require_relative "../project"
+require_relative "vm_credential"
+
+module Maf
+  module Shared
+    module Harness
+      AGENTS_DIR = File.join(".maf", "agents")
+      # The command of the graphify MCP server. It runs in the project folder.
+      VAULT_MCP = %w[ruby .maf/bin/vault mcp].freeze
+
+      # RoleFiles: maf add writes one role file per agent.
+      module RoleFiles
+        # The folder where the harness reads role files. maf links it to
+        # .maf/agents/<name>/. nil: the harness reads no role folder.
+        def role_dir = nil
+        def role_path(role) = role_dir && File.join(AGENTS_DIR, name, "#{role}.md")
+
+        # settings: the data of .maf/config.json. A harness that keeps role
+        # files outside the project reads its folder there.
+        def role_destination(project, role, _settings = {}) = role_path(role) && File.join(project, role_path(role))
+
+        # An ERB template. It gets role, title, description, can_edit, project, prompt, and model.
+        def role_template = raise(NotImplementedError, "#{name}: role_template")
+        def render_role(values) = ERB.new(role_template, trim_mode: "-").result_with_hash(**values)
+
+        # nil: the harness lists no models, so every name counts as known.
+        def models = nil
+        # list: the models of the harness. A caller with a cached list passes it.
+        def known_model?(model, list = models) = list.nil? || list.include?(model)
+        def default_model = nil
+
+        # The command that sets the model, for a harness whose role file cannot set it.
+        def model_hint(_model) = nil
+
+        # How an idle agent waits for work. :watch - a watcher wakes the idle
+        # session. :await - the stop hook waits after `coord await`.
+        # :poll - the agent blocks in `coord next --wait`.
+        def wait = :poll
+
+        # One more rule line for the architect prompt, or nil.
+        def architect_rule = nil
+      end
+
+      # Setup: maf add, maf start, bootstrap, untrack, retire, and uninstall.
+      module Setup
+        # The graphify MCP server in a config file of the flow:
+        # { file: ".maf/mcp/x.json", key: "mcpServers", entry: {...} }. nil: no file.
+        def mcp = nil
+        # The command that adds the server to a global config of the harness, or nil.
+        def mcp_command(_server, _vault) = nil
+        # The project file where an older maf wrote the MCP server, or nil.
+        def legacy_mcp_file = nil
+
+        # maf add installs the hooks. A truthy result: the user has steps left.
+        def install_hooks(_project) = nil
+        # maf start refreshes the hooks in the worktree before the session starts.
+        def runtime_hooks(_worktree) = nil
+        # Bootstrap installs the hooks of the harness only if this folder exists.
+        def bootstrap_dir = nil
+
+        # Uninstall: objects with #steps that remove the files of the flow.
+        def cleaners(_project) = []
+        # Uninstall and untrack: objects with #steps that remove what an older
+        # maf wrote into the project's own files.
+        def legacy_cleaners(_project) = []
+        # Files outside the project that uninstall keeps: other projects can use them.
+        def global_files = []
+
+        def vm_install = nil
+        def vm_credentials = []
+        def vm_login_hint = "maf vm shell, then start #{command} and log in"
+
+        # The top folder of the harness. maf retire ignores changes in it.
+        def home_dir = role_dir&.split("/")&.first
+        # Files that the flow writes in a worktree. coord keeps them out of git.
+        def runtime_files = []
+        # Folders that uninstall removes when they are empty. Children come first.
+        def empty_dirs = [role_dir, home_dir].compact.uniq
+
+        # The paths that git tracks for the flow. tracked.call(path) lists the
+        # tracked files below path. By default, the links into .maf/agents/.
+        def untrack_paths(root, tracked)
+          return [] unless role_dir
+
+          tracked.call(role_dir).select do |path|
+            File.symlink?(File.join(root, path)) && File.readlink(File.join(root, path)).include?(AGENTS_DIR)
+          end
+        end
+      end
+
+      # Run: maf start (an interactive session) and the dispatcher (one run per task).
+      module Run
+        # The command of an interactive session.
+        def launch(_role, _model) = raise(NotImplementedError, "#{name}: launch")
+        def launch_env = {}
+
+        def sandbox_dirs = []
+        def sandbox_state = []
+        def sandbox_prefixes = []
+        def sandbox_protected = []
+        def sandbox_project = []
+        def in_dir(dir, names) = names.map { |name| File.join(dir, name) }
+        def sandbox_placeholders = sandbox_protected.reject { |path| path.end_with?(".md", ".yaml") }
+        def sandboxed(cmd) = cmd
+
+        # The command of one dispatched run. session_id is nil for a fresh session.
+        def build_command(_config, _prompt, _session_id) = raise(NotImplementedError, "#{name}: build_command")
+        def run_env(_config) = {}
+        # The dispatcher calls it once after it parses the options.
+        def prepare(config) = config
+        # Seconds that the prompt cache of the harness stays warm, or nil for the default.
+        def cache_window = nil
+        def peak_rate?(_config) = false
+
+        # The parts of the run output. nil: the harness does not report it.
+        def stale_session?(_output) = false
+        def session_id(_output) = nil
+        def result_text(_output) = nil
+        def usage(_output) = nil
+        def context(_output) = nil
+        def model(_output) = nil
+
+        # A file of the flow in .maf/ of the main checkout. The dispatcher finds
+        # .maf/ next to its coordination folder, which COORD_DIR can move.
+        def flow_file(*parts) = File.join(Project.root, ".maf", *parts)
+        def run_file(config, *parts) = File.join(File.dirname(config.coord_dir), *parts)
+        def flag_if(flag, path) = File.exist?(path) ? [flag, path] : []
+
+        def present(value) = value.to_s.empty? ? nil : value
+        def model_flag(model, flag = "--model") = model ? [flag, model] : []
+        def resume(session_id, *flag) = session_id ? [*flag, session_id] : []
+      end
+    end
+  end
+end

data/lib/maf/shared/harness/output.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# maf shared library - code that the maf CLI and the scripts in .maf/bin share.
+# The installer copies this folder to .maf/lib/maf/shared/. maf update replaces it.
+# Use the Ruby stdlib only: a script loads this file without a gem bundle.
+require "json"
+
+module Maf
+  module Shared
+    module Harness
+      # Events reads the JSON event lines of a harness run. Each harness takes
+      # its session ID from one specific event, never from free text, so a
+      # prompt or a handoff note that the agent echoes cannot supply a false ID.
+      module Events
+        def self.all(output) = output.lines.filter_map { |line| parse(line.strip) }
+
+        def self.last(output, &match) = all(output).reverse.find(&match) || {}
+
+        def self.parse(line)
+          event = line.start_with?("{") ? JSON.parse(line) : nil
+          event.is_a?(Hash) ? event : nil
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
+      # Usage turns the token usage of a harness into one shape.
+      #
+      # input_tokens counts every input token, cache reads included.
+      # cached_input_tokens counts the cache reads, which cost a fraction of the
+      # input price. cache_write_input_tokens counts the cache writes, which cost
+      # more than the input price. Claude Code reports cache reads and cache
+      # writes outside its input_tokens, so they are added. Codex reports them inside.
+      module Usage
+        def self.normalize(data)
+          return nil unless data.is_a?(Hash)
+
+          { "input_tokens" => input(data),
+            "cached_input_tokens" => int(data, "cached_input_tokens", "cache_read_input_tokens"),
+            "cache_write_input_tokens" => int(data, "cache_write_input_tokens", "cache_creation_input_tokens"),
+            "output_tokens" => int(data, "output_tokens", "completion_tokens") }
+        end
+
+        def self.input(data)
+          int(data, "input_tokens", "prompt_tokens") + int(data, "cache_read_input_tokens") +
+            int(data, "cache_creation_input_tokens")
+        end
+
+        def self.int(data, *names) = data.values_at(*names).compact.first.to_i
+
+        def self.sum(list) = list.empty? ? nil : list.reduce { |total, usage| total.merge(usage) { |_, a, b| a + b } }
+      end
+    end
+  end
+end

data/lib/maf/shared/harness/traits.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# maf shared library - code that the maf CLI and the scripts in .maf/bin share.
+# The installer copies this folder to .maf/lib/maf/shared/. maf update replaces it.
+# Use the Ruby stdlib only: a script loads this file without a gem bundle.
+require_relative "base"
+
+module Maf
+  module Shared
+    module Harness
+      # ResultEvent reads a run that ends with one JSON result event: the
+      # session ID, the result text, and the usage.
+      module ResultEvent
+        def result_event(output) = Events.last(output) { |event| result_event?(event) }
+        def result_event?(event) = event["type"] == "result"
+        def result_text(output) = result_event(output)["result"]
+        def session_id(output) = present(result_event(output)["session_id"])
+        def usage(output) = Usage.normalize(result_event(output)["usage"])
+      end
+
+      # PrependsRole is for a CLI without an agent flag. A fresh session gets
+      # the role file text in front of the prompt. A resumed session has it.
+      module PrependsRole
+        FRONT_MATTER = /\A---\n.*?\n---\n+/m
+
+        def first_prompt(role, prompt, session_id) = session_id ? prompt : role_text(role) + prompt
+
+        def role_text(role)
+          path = role_path(role)
+          path && File.exist?(path) ? "#{File.read(path).sub(FRONT_MATTER, "")}\n\n" : ""
+        end
+      end
+    end
+  end
+end

data/lib/maf/shared/harness/vm_credential.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# maf shared library - code that the maf CLI and the scripts in .maf/bin share.
+# The installer copies this folder to .maf/lib/maf/shared/. maf update replaces it.
+# Use the Ruby stdlib only: a script loads this file without a gem bundle.
+
+module Maf
+  module Shared
+    module Harness
+      # VmCredential is one login file of a harness that maf vm can copy into the VM.
+      class VmCredential
+        attr_reader :dest
+
+        def self.file(path, dest) = new(dest) { File.read(path) if File.file?(path) }
+
+        def self.keychain(service, dest)
+          new(dest) do
+            text = IO.popen(["security", "find-generic-password", "-s", service, "-w"], err: File::NULL, &:read)
+            text unless text.to_s.strip.empty?
+          end
+        end
+
+        def initialize(dest, &read)
+          @dest = dest
+          @read = read
+        end
+
+        def read
+          @read.call
+        rescue SystemCallError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/maf/shared/harness.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# maf shared library - code that the maf CLI and the scripts in .maf/bin share.
+# The installer copies this folder to .maf/lib/maf/shared/. maf update replaces it.
+# Use the Ruby stdlib only: a script loads this file without a gem bundle.
+#
+# harness.rb loads the harness registry and every harness in harnesses/.
+# To add a harness, add one file there. See harness/defaults.rb for the methods.
+require_relative "harness/base"
+require_relative "harness/traits"
+
+Dir.glob(File.join(__dir__, "harnesses", "*.rb")).each { |file| require file }