maf 0.1.0 → 0.3.0

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 }

data/lib/maf/shared/harnesses/claude.rb

@@ -0,0 +1,137 @@
+# 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 "../harness/traits"
+
+module Maf
+  module Shared
+    module Harnesses
+      # Claude Code. `--agent` loads .claude/agents/<role>.md. The board-watch
+      # hook wakes an idle session. Bootstrap installs the hooks into
+      # .maf/claude/settings.json, and maf start passes the file with --settings.
+      class Claude < Harness::Base
+        include Harness::ResultEvent
+
+        def role_dir = ".claude/agents"
+
+        def role_template = <<~ERB
+          ---
+          # >>> multi-agent-flow >>>
+          name: <%= role %>
+          description: <%= description %>
+          <% if model -%>
+          model: <%= model %>
+          <% end -%>
+          <%# A tools list blocks each MCP tool that it does not name. -%>
+          <% if can_edit -%>
+          tools: Read, Write, Edit, Bash, Grep, Glob, mcp__graphify
+          <% else -%>
+          tools: Read, Bash, Grep, Glob, mcp__graphify
+          <% end -%>
+          ---
+
+          <%= prompt %>
+        ERB
+
+        # Claude Code has no command that lists models. The aliases follow the
+        # newest model of each family. A full ID is claude-<family>-<version>.
+        MODELS = %w[claude-opus-5-5 claude-sonnet-5-5 claude-haiku-5-5 claude-fable-5-1 opus sonnet haiku fable].freeze
+        MODEL_NAME = /\A(?:(?:opus|sonnet|haiku|fable)(?:\[1m\])?|opusplan|default|best|
+                       (?:[\w.-]+\.)?(?:anthropic\.)?claude-(?:opus|sonnet|haiku|fable)-\d[\w.:@\[\]-]*)\z/x
+
+        def models = MODELS
+        def known_model?(model, _list = nil) = model.match?(MODEL_NAME)
+        def default_model = "claude-opus-5-5"
+        EFFORTS = %w[low medium high xhigh max].freeze
+        def efforts(_model = nil) = EFFORTS
+
+        def wait = :watch
+        def vm_install = "curl -fsSL https://claude.ai/install.sh | bash"
+        LOGIN = ".claude/.credentials.json"
+        def vm_credentials = [RUBY_PLATFORM.include?("darwin") ? keychain_login : file_login]
+        def keychain_login = Harness::VmCredential.keychain("Claude Code-credentials", LOGIN)
+        def file_login = Harness::VmCredential.file(File.join(sandbox_dirs.first, ".credentials.json"), LOGIN)
+
+        def sandbox_dirs = [ENV.fetch("CLAUDE_CONFIG_DIR", File.join(Dir.home, ".claude"))]
+        def sandbox_prefixes = [File.join(Dir.home, ".claude.json")]
+        PROTECTED = %w[settings.json settings.local.json CLAUDE.md hooks skills agents commands plugins
+                       output-styles rules].freeze
+        def sandbox_protected = in_dir(sandbox_dirs.first, PROTECTED)
+        STATE = %w[projects sessions session-env shell-snapshots file-history todos tasks plans paste-cache statsig
+                   telemetry ide debug logs cache backups jobs downloads feedback state daemon daemon.log* daemon-auth-*
+                   history.jsonl* stats-cache.json* *-cache.json* .last-* .credentials* .claude.json*].freeze
+        LOGS = ["Library/Caches/claude-cli-nodejs", ".cache/claude-cli-nodejs"].freeze
+        def sandbox_state = in_dir(sandbox_dirs.first, STATE) + in_dir(Dir.home, LOGS)
+        PROJECT = %w[.mcp.json .claude/settings.json .claude/settings.local.json .claude/hooks .claude/commands
+                     .claude/skills .claude/agents .claude/output-styles .claude/rules].freeze
+        def sandbox_project = PROJECT
+
+        # Only Claude Code has ScheduleWakeup.
+        def architect_rule
+          "- Never call ScheduleWakeup with `stop:false` and no `prompt`. " \
+            "The call fails. Poll worker status through the task tool instead."
+        end
+
+        def mcp
+          { file: ".maf/mcp/claude.json", key: "mcpServers",
+            entry: { "command" => Harness::VAULT_MCP.first, "args" => Harness::VAULT_MCP.drop(1) } }
+        end
+
+        def legacy_mcp_file = ".mcp.json"
+        # An older maf wrote the hooks into the project's .claude/settings.json.
+        def legacy_cleaners(project) = [Uninstall::ClaudeSettings.new(project)]
+        def bootstrap_dir = ".claude"
+
+        # The hook commands run in the worktree. The settings file is in the main project.
+        def runtime_hooks(_worktree)
+          root = Project.root
+          settings = File.join(root, Bootstrap::CLAUDE_SETTINGS)
+          Bootstrap::ClaudeSettings.new(Bootstrap::Project.new(root, false)).configure(settings)
+        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.
+        def launch(role, model, effort = nil)
+          prompt = "Read #{role_path(role)} and follow it exactly. Start your work loop now."
+          ["claude", *flag_if("--settings", flow_file("claude", "settings.json")),
+           *flag_if("--mcp-config", flow_file("mcp", "claude.json")), *model_flag(model), *effort_flag(effort),
+           "--", prompt]
+        end
+
+        # `claude -p` prints one JSON object with session_id and result.
+        # LEAN starts no MCP server outside --mcp-config and lists no skill.
+        # The user's CLAUDE.md and hooks stay.
+        LEAN = %w[--strict-mcp-config --disable-slash-commands].freeze
+
+        def build_command(config, prompt, session_id)
+          cmd = %w[claude -p --output-format json --permission-mode bypassPermissions --agent] + [config.role]
+          cmd += model_flag(config.model) + effort_flag(config.effort)
+          cmd += LEAN if config.lean
+          cmd + flag_if("--mcp-config", run_file(config, "mcp", "claude.json")) +
+            resume(session_id, "--resume") + ["--", prompt]
+        end
+
+        def stale_session?(output) = output.include?("No conversation found with session ID")
+        def result_event?(event) = event.key?("result")
+        # The result names each model that the run used. The main model comes first.
+        def model(output) = result_event(output)["modelUsage"]&.keys&.first
+
+        # A tool_use block, then a tool_result block with the same ID.
+        def transcript_calls(id)
+          blocks = jsonl(transcript_path(id)).flat_map { |event| Array(event.dig("message", "content")).grep(Hash) }
+          sizes = result_sizes(blocks)
+          blocks.select { |b| b["type"] == "tool_use" }
+                .map { |b| [b["name"], b.dig("input", "command"), sizes[b["id"]]] }
+        end
+
+        def result_sizes(blocks)
+          blocks.select { |b| b["type"] == "tool_result" }.to_h { |b| [b["tool_use_id"], b["content"].to_s.size] }
+        end
+
+        def transcript_path(id) = Dir.glob(File.join(Dir.home, ".claude", "projects", "*", "#{id}.jsonl")).first
+      end
+    end
+  end
+end

data/lib/maf/shared/harnesses/codex.rb

@@ -0,0 +1,202 @@
+# 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 "../harness/traits"
+
+module Maf
+  module Shared
+    module Harnesses
+      # Codex. It has no agent flag, so a fresh session gets the role file in
+      # front of the prompt. Codex returns a long tool call to the model about
+      # every 30 seconds, so an idle agent runs `coord await`, and the stop
+      # hook in .codex/hooks.json waits for work outside the model.
+      class Codex < Harness::Base
+        include Harness::PrependsRole
+
+        def role_dir = ".codex/prompts"
+
+        def role_template = <<~ERB
+          <!-- >>> multi-agent-flow >>> -->
+          # <%= title %>
+
+          <% if model -%>
+          > Model: `<%= model %>` (Codex sets the model at launch: `codex -m <%= model %>`)
+          <% end -%>
+          <%= prompt %>
+        ERB
+
+        def model_hint(model) = "codex -m #{model}"
+        def wait = :await
+        def home = ENV.fetch("CODEX_HOME", File.join(Dir.home, ".codex"))
+        def sandbox_dirs = [home]
+        PROTECTED = %w[config.toml hooks.json hooks rules skills plugins prompts packages AGENTS.md
+                       AGENTS.override.md].freeze
+        def sandbox_protected = in_dir(home, PROTECTED)
+        def sandbox_placeholders = super - [File.join(home, "packages")]
+        STATE = %w[sessions archived_sessions memories log logs* *.sqlite* history.jsonl* session_index.jsonl*
+                   auth.json* models_cache.json* version.json* installation_id* .sqlite-maintenance.lock tmp .tmp
+                   shell_snapshots attachments thread-writer-locks tui-*].freeze
+        def sandbox_state = in_dir(home, STATE)
+        PROJECT = %w[.codex/config.toml .codex/hooks.json .codex/hooks .codex/rules .codex/prompts
+                     .agents/skills].freeze
+        def sandbox_project = PROJECT
+        def vm_install = "sudo npm install -g @openai/codex"
+        def vm_credentials = [Harness::VmCredential.file(File.join(home, "auth.json"), ".codex/auth.json")]
+
+        def sandboxed(cmd)
+          return cmd if cmd.include?("--dangerously-bypass-approvals-and-sandbox")
+
+          [cmd.first, "--sandbox", "danger-full-access", *cmd.drop(1)]
+        end
+
+        # Codex keeps the model list of the account in a cache file. Hidden models are internal.
+        def models = CodexModels.listed(home)
+        # Without a pinned model, Codex runs the model of its config file.
+        def efforts(model = nil) = CodexModels.efforts(model || CodexModels.configured(home), home)
+        def effort_flag(effort) = effort ? ["-c", "model_reasoning_effort=#{effort.to_s.dump}"] : []
+
+        # Codex keeps MCP servers in a global user file. maf does not edit it.
+        def mcp_command(server, vault) = "codex mcp add #{server} -- ruby #{vault} mcp"
+
+        def install_hooks(project)
+          %w[next-task.rb session-guard.rb].each { |name| Flow::HookFiles.install(project, name) }
+          runtime_hooks(project)
+          Flow::LegacyCodexHook.new.remove
+          nil
+        end
+
+        def runtime_hooks(worktree) = Flow::CodexHooks.new(worktree).install
+        def runtime_files = [".codex/hooks.json"]
+        def cleaners(project) = [Uninstall::CodexHooks.new(project)]
+
+        # An older maf tracked the role files. A hooks file with only the flow hooks belongs to the flow.
+        def untrack_paths(root, tracked)
+          hooks = tracked.call(".codex/hooks.json").select { |file| Flow::CodexHooks.flow_only?(File.join(root, file)) }
+          tracked.call(role_dir) + hooks
+        end
+
+        def launch(role, model, effort = nil)
+          abort "setup_agent: #{role_path(role)} missing." unless File.exist?(role_path(role))
+
+          warn_untrusted
+          ["codex", *no_daemon, "--add-dir", File.join(Project.root, ".maf", "coordination"), *model_flag(model),
+           *effort_flag(effort), File.read(role_path(role))]
+        end
+
+        def no_daemon = codex_help.include?("--no-daemon") ? ["--no-daemon"] : []
+
+        def codex_help
+          IO.popen(%w[codex --help], err: File::NULL, &:read)
+        rescue SystemCallError
+          ""
+        end
+
+        UNTRUSTED = "maf: Codex does not trust the hooks in %<file>s yet. Without the hooks, the session " \
+                    "records no token usage, and coord await cannot wake it. The sandbox cannot save the trust: " \
+                    "start codex once in %<root>s without the sandbox, and trust the hooks when Codex asks."
+
+        def warn_untrusted
+          root = File.realpath(Project.root)
+          hooks = File.join(root, ".codex", "hooks.json")
+          config = File.join(home, "config.toml")
+          trusted = File.exist?(config) && File.read(config).include?("#{hooks}:stop:")
+          warn format(UNTRUSTED, file: hooks, root: root) if File.exist?(hooks) && !trusted
+        end
+
+        # The OpenAI cache of Codex is best effort: a probe missed it after 5 idle minutes.
+        def cache_window = 300
+
+        def build_command(config, prompt, session_id)
+          cmd = %w[codex exec] + (session_id ? ["resume"] : [])
+          cmd += %w[--json --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox]
+          cmd += model_flag(config.model, "-m") + effort_flag(config.effort)
+          cmd += lean_flags if config.lean
+          cmd + resume(session_id) + [first_prompt(config.role, prompt, session_id)]
+        end
+
+        def lean_flags = CodexLean.flags(home)
+        def stale_session?(output) = output.include?("no rollout found for thread id")
+
+        def result_text(output)
+          Harness::Events.last(output) { |event| event.dig("item", "type") == "agent_message" }.dig("item", "text")
+        end
+
+        def session_id(output)
+          present(Harness::Events.last(output) { |event| event["type"] == "thread.started" }["thread_id"])
+        end
+
+        # Codex reports the usage of each turn in a turn.completed event.
+        def usage(output)
+          turns = Harness::Events.all(output).select { |event| event["type"] == "turn.completed" }
+          Harness::Usage.sum(turns.filter_map { |event| Harness::Usage.normalize(event["usage"]) })
+        end
+
+        def transcript_calls(id)
+          path = Dir.glob(File.join(Dir.home, ".codex", "sessions", "**", "rollout-*#{id}.jsonl")).first
+          CodexTranscript.calls(jsonl(path).map { |event| event["payload"] || {} })
+        end
+      end
+
+      # CodexModels reads the model list of the account from the cache file of Codex.
+      module CodexModels
+        def self.listed(home) = cache(home)&.select { |m| m["visibility"] == "list" }&.map { |m| m["slug"] }
+
+        # nil: no model, or a model outside the cache.
+        def self.efforts(model, home)
+          entry = model && cache(home)&.find { |m| m["slug"] == model }
+          entry&.fetch("supported_reasoning_levels", nil)&.map { |level| level["effort"] }
+        end
+
+        def self.configured(home)
+          path = File.join(home, "config.toml")
+          top = File.exist?(path) ? File.read(path).split(/^\[/, 2).first.to_s : ""
+          top[/^model\s*=\s*"([^"]+)"/, 1]
+        end
+
+        def self.cache(home)
+          JSON.parse(File.read(File.join(home, "models_cache.json"))).fetch("models")
+        rescue SystemCallError, JSON::ParserError, KeyError, NoMethodError
+          nil
+        end
+      end
+
+      # CodexLean drops the parts of the user's Codex setup that a one-shot run
+      # does not use. Each one adds tool schemas, skill lists, or MCP calls
+      # to every model call. Only the graphify server of this project stays.
+      module CodexLean
+        FEATURES = %w[plugins apps browser_use computer_use multi_agent].freeze
+        SERVER = /^\[mcp_servers\.([\w-]+)\]\s*$/
+
+        def self.flags(home) = FEATURES.flat_map { |name| ["--disable", name] } + servers(home).flat_map { |s| off(s) }
+        def self.off(server) = ["-c", "mcp_servers.#{server}.enabled=false"]
+        def self.keep = "graphify-#{File.basename(Project.root)}"
+
+        def self.servers(home)
+          path = File.join(home, "config.toml")
+          File.exist?(path) ? File.read(path).scan(SERVER).flatten.uniq - [keep] : []
+        end
+      end
+
+      # CodexTranscript reads the tool calls of a Codex session: a
+      # custom_tool_call or function_call, then its output with the same call_id.
+      module CodexTranscript
+        def self.calls(payloads)
+          sizes = output_sizes(payloads)
+          payloads.select { |p| %w[custom_tool_call function_call].include?(p["type"]) }
+                  .map { |p| [p["name"], command(p), sizes[p["call_id"]]] }
+        end
+
+        def self.output_sizes(payloads)
+          payloads.select { |p| p["type"].to_s.end_with?("_output") }.to_h { |p| [p["call_id"], p["output"].to_s.size] }
+        end
+
+        def self.command(payload)
+          text = (payload["input"] || payload["arguments"]).to_s
+          text[/cmd["']?\s*:\s*["']((?:[^"'\\]|\\.)*)/, 1] || text
+        end
+      end
+    end
+  end
+end

data/lib/maf/shared/harnesses/cursor.rb

@@ -0,0 +1,120 @@
+# 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 "open3"
+require_relative "../harness/traits"
+
+module Maf
+  module Shared
+    module Harnesses
+      # The Cursor CLI (`agent`). The role files in .cursor/agents/ are Cursor
+      # subagents. The CLI has no flag that picks one, so maf start names the
+      # role file in the prompt, and the dispatcher puts the role text in front
+      # of the first prompt. Cursor reads MCP servers only from .cursor/mcp.json,
+      # so the flow passes no MCP config. Cursor has no wake-up hook yet.
+      class Cursor < Harness::Base
+        include Harness::ResultEvent
+        include Harness::PrependsRole
+
+        def command = "agent"
+        def role_dir = ".cursor/agents"
+        def sandbox_dirs = [File.join(Dir.home, ".cursor"), File.join(Dir.home, ".config", "cursor")]
+        PROTECTED = %w[cli-config.json hooks.json mcp.json hooks agents skills plugins rules].freeze
+        def sandbox_protected = in_dir(File.join(Dir.home, ".cursor"), PROTECTED)
+        def sandbox_placeholders = super - [File.join(Dir.home, ".cursor", "cli-config.json")]
+        STATE = %w[.cursor/agent-cli-state.json* .cursor/statsig-cache.json* .cursor/chats .cursor/projects
+                   .cursor/ai-tracking .config/cursor/auth.json* .config/cursor/*.lock].freeze
+        def sandbox_state = in_dir(Dir.home, STATE)
+        PROJECT = %w[.cursor/mcp.json .cursor/hooks.json .cursor/hooks .cursor/cli.json .cursor/agents].freeze
+        def sandbox_project = PROJECT
+        def vm_install = "curl -fsSL https://cursor.com/install | bash"
+        def vm_login_hint = "maf vm shell, then NO_OPEN_BROWSER=1 agent login (or export CURSOR_API_KEY)"
+
+        def role_template = <<~ERB
+          ---
+          # >>> multi-agent-flow >>>
+          name: <%= role %>
+          description: <%= description %>
+          <% if model -%>
+          model: <%= Maf::Shared::Harnesses::CursorModels.name(model, effort) %>
+          <% end -%>
+          readonly: <%= !can_edit %>
+          ---
+
+          <%= prompt %>
+        ERB
+
+        def launch(role, model, effort = nil)
+          warn "maf: Cursor takes the level in the model name. Without a model, maf drops --effort." if effort && !model
+          ["agent", *model_flag(CursorModels.name(model, effort)),
+           "Read #{role_path(role)} and follow it exactly. Start your work loop now."]
+        end
+
+        # `agent -p --output-format json` prints one result object with session_id and result.
+        def build_command(config, prompt, session_id)
+          %w[agent -p --output-format json --force --trust
+             --approve-mcps] + model_flag(CursorModels.name(config.model, config.effort)) +
+            resume(session_id, "--resume") + [first_prompt(config.role, prompt, session_id)]
+        end
+
+        # Cursor has no effort flag. The level is a part of the model name, so
+        # maf lists each model without its level, and the levels of each model.
+        def models = CursorModels.bases
+
+        def known_model?(model, list = models)
+          list.nil? || list.include?(model) || CursorModels.listed.include?(model)
+        end
+
+        def efforts(model = nil) = CursorModels.efforts(model)
+        def effort_required?(model) = CursorModels.effort_required?(model)
+
+        # A failed run prints no JSON, only an error on stderr. So a resume
+        # without a result event and with "not found" is stale. Cursor reports no token usage.
+        def stale_session?(output) = result_event(output).empty? && output.match?(/not found/i)
+      end
+
+      # CursorModels reads `agent --list-models`. A name is BASE-LEVEL or
+      # BASE-LEVEL-fast, for example gpt-5.3-codex-high-fast.
+      module CursorModels
+        LEVELS = %w[low medium high xhigh max].freeze
+        LEVEL = /-(#{LEVELS.join("|")})(?=(?:-fast)?\z)/
+
+        def self.listed
+          return @listed if defined?(@listed)
+
+          @listed = read
+        end
+
+        def self.read
+          out, status = Open3.capture2("agent", "--list-models", err: File::NULL)
+          status.success? ? out.scan(/^(\S+) - /).flatten : nil
+        rescue SystemCallError
+          nil
+        end
+
+        def self.bases = listed&.map { |model| model.sub(LEVEL, "") }&.uniq
+
+        # nil: maf cannot read the list. A name with a level takes no other level.
+        def self.efforts(model)
+          return nil unless listed
+          return [] if model.nil? || (model.match?(LEVEL) && listed.include?(model))
+
+          LEVELS.select { |level| listed.include?(name(model, level)) }
+        end
+
+        # A base that Cursor does not list by itself runs only with a level.
+        def self.effort_required?(model) = !listed.nil? && !listed.include?(model) && !efforts(model).to_a.empty?
+
+        # A name with a level gets the new level instead.
+        def self.name(model, effort)
+          return model unless model && effort
+
+          model = model.sub(LEVEL, "")
+          model.end_with?("-fast") ? model.sub(/-fast\z/, "-#{effort}-fast") : "#{model}-#{effort}"
+        end
+      end
+    end
+  end
+end