maf 0.1.0 → 0.2.0

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

@@ -0,0 +1,134 @@
+# 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"
+
+        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)
+          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), "--", 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)
+          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,173 @@
+# 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
+          models = JSON.parse(File.read(File.join(Dir.home, ".codex", "models_cache.json"))).fetch("models")
+          models.select { |m| m["visibility"] == "list" }.map { |m| m["slug"] }
+        rescue SystemCallError, JSON::ParserError, KeyError, NoMethodError
+          nil
+        end
+
+        # 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)
+          abort "setup_agent: #{role_path(role)} missing." unless File.exist?(role_path(role))
+
+          warn_untrusted
+          ["codex", "--add-dir", File.join(Project.root, ".maf", "coordination"), *model_flag(model),
+           File.read(role_path(role))]
+        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")
+          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
+
+      # 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,64 @@
+# 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
+      # 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: <%= model %>
+          <% end -%>
+          readonly: <%= !can_edit %>
+          ---
+
+          <%= prompt %>
+        ERB
+
+        def launch(role, model)
+          ["agent", *model_flag(model), "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(config.model) +
+            resume(session_id, "--resume") + [first_prompt(config.role, prompt, session_id)]
+        end
+
+        # 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
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# 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"
+require_relative "../roles"
+
+module Maf
+  module Shared
+    module Harnesses
+      # Hermes loads role files as skills from <hermes_dir>/<project>-<role>/,
+      # outside the project. `--skills <project>-<role>` loads one. Hermes has
+      # no agent flag and cannot be woken, so an idle agent blocks in
+      # `coord next --wait`. A role with can_edit false starts without the
+      # file-writing toolsets. Hermes keeps hooks and MCP servers in global
+      # files, so maf prints the commands that add them.
+      class Hermes < Harness::Base
+        include Harness::ResultEvent
+
+        DEFAULT_DIR = File.join(Dir.home, ".hermes", "skills")
+        MAX_TURNS = 50
+        # Stop Hermes before the dispatcher kills it, so it can still write its
+        # result event. NOTE: assets/dispatcher Spawn::GRACE.
+        KILL_GRACE = 5
+
+        def sandbox_dirs = [File.join(Dir.home, ".hermes")]
+        PROTECTED = %w[config.yaml .env shell_init.sh SOUL.md hooks agent-hooks shell-hooks-allowlist.json bin scripts
+                       cron skills plugins hermes-agent].freeze
+        def sandbox_protected = in_dir(File.join(Dir.home, ".hermes"), PROTECTED)
+        STATE = %w[sessions logs cache memories state *.db* pastes composer-pastes image_cache audio_cache locks
+                   pending runtime telemetry terminal-sessions processes.json* spawn-ledger.json* auth.json* auth.lock
+                   google_token.json* models_dev_cache* provider_models_cache.json* context_length_cache.yaml*
+                   .hermes_history* .*lock*].freeze
+        def sandbox_state = in_dir(File.join(Dir.home, ".hermes"), STATE)
+        def sandbox_placeholders = super - [File.join(Dir.home, ".hermes", "hermes-agent")]
+        def vm_credentials = [Harness::VmCredential.file(File.join(Dir.home, ".hermes", ".env"), ".hermes/.env")]
+
+        def role_destination(project, role, settings = {})
+          File.join(settings["hermes_dir"] || DEFAULT_DIR, "#{File.basename(project)}-#{role}", "SKILL.md")
+        end
+
+        def role_template = <<~ERB
+          ---
+          # >>> multi-agent-flow >>>
+          name: <%= role %>
+          description: <%= description %>
+          ---
+
+          # <%= title %>
+
+          <% if model -%>
+          > Model: `<%= model %>` (Hermes sets the model with `hermes model`)
+          <% end -%>
+          <%= prompt %>
+        ERB
+
+        def model_hint(_model) = "hermes model"
+        def mcp_command(server, vault) = "hermes mcp add #{server} --command ruby --args #{vault} mcp"
+        def install_hooks(_project) = Flow::HermesHookSetup.new.install
+        def global_files = [File.join(Dir.home, ".hermes", "agent-hooks", "next-task.sh")]
+
+        # The skill name uses the main checkout's name, from the project root
+        # and from a worktree alike.
+        def skill_name(role) = "#{File.basename(Project.root)}-#{role}"
+
+        # The skill that maf add generated for the role, or nil.
+        def skill(role)
+          dir = Project.manifest.fetch("hermes_dir", DEFAULT_DIR)
+          File.exist?(File.join(dir, skill_name(role), "SKILL.md")) ? skill_name(role) : nil
+        end
+
+        def read_only?(role)
+          Project.manifest.fetch("agents", []).any? { |agent| agent["role"] == role && agent["can_edit"] == false }
+        end
+
+        def tools(role) = read_only?(role) ? ["-t", Roles::READ_ONLY_TOOLSETS] : []
+
+        PROMPT = "Follow the coordination rules of your role skill as role %<role>s. " \
+                 "Run coord inbox, then coord next --wait. Claim a task, do the work, finish it. Repeat."
+        LEAD_PROMPT = "Follow your role skill and its coordination rules as role %<role>s. " \
+                      "You are a lead role. Never claim a task. Run coord inbox --wait and handle each message."
+
+        # `-q` on a TTY seeds an interactive session with the prompt.
+        def launch(role, model)
+          prompt = format(Roles::LEADS.include?(role) ? LEAD_PROMPT : PROMPT, role: role)
+          ["hermes", "chat", *skill(role)&.then { |name| ["--skills", name] }, *model_flag(model), *tools(role),
+           "-q", prompt]
+        end
+
+        # --no-skill drops the skill. Without --skill, the generated skill of the role loads.
+        def prepare(config)
+          config.skill = nil if config.no_skill
+          config.skill ||= skill(config.role) unless config.no_skill
+          config.max_turns ||= MAX_TURNS
+          config
+        end
+
+        # `hermes chat --oneshot` with JSONL output and the skill preloaded.
+        def build_command(config, prompt, session_id)
+          cmd = %w[hermes chat --oneshot --yolo --format stream-json -Q]
+          cmd += [*(["--skills", config.skill] if config.skill), *model_flag(config.model), *tools(config.role)]
+          cmd += ["--max-turns", config.max_turns.to_s, "--run-budget", [config.timeout - KILL_GRACE, 1].max.to_s]
+          cmd + resume(session_id, "--resume") + ["-q", prompt]
+        end
+
+        def stale_session?(output) = output.include?("Session not found")
+        def result_text(output) = result_event(output)["text"]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,169 @@
+# 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
+      # OpencodeSandbox holds the sandbox paths of opencode.
+      module OpencodeSandbox
+        DATA_DIRS = %w[.local/share/opencode .local/state/opencode .config/opencode].freeze
+        def sandbox_dirs = DATA_DIRS.map { |dir| File.join(Dir.home, dir) }
+        PROTECTED = %w[opencode.json opencode.jsonc config.json package.json node_modules plugin plugins agent agents
+                       command commands skills AGENTS.md].freeze
+        def sandbox_protected = in_dir(sandbox_dirs.last, PROTECTED)
+        STATE = %w[auth.json* log opencode.db* repos snapshot tool-output storage project].freeze
+        def sandbox_state = [*in_dir(sandbox_dirs.first, STATE), File.join(sandbox_dirs[1], "*")]
+        def sandbox_project = %w[opencode.json opencode.jsonc .opencode]
+      end
+
+      # opencode. `--agent` loads .opencode/agents/<role>.md. The board-watch
+      # plugin in .opencode/plugins/ wakes an idle session. opencode merges the
+      # file in OPENCODE_CONFIG with the project's opencode.json.
+      class Opencode < Harness::Base
+        include OpencodeSandbox
+
+        def role_dir = ".opencode/agents"
+
+        def role_template = <<~ERB
+          ---
+          # >>> multi-agent-flow >>>
+          description: <%= description %>
+          mode: all
+          <% if model -%>
+          model: <%= model %>
+          <% end -%>
+          temperature: 0.1
+          permission:
+            edit: <%= can_edit ? "allow" : "deny" %>
+            bash: allow
+            # Worktrees live inside the project. The board, the artifacts, and git
+            # data are outside the worktree, so opencode would ask for each access.
+            external_directory:
+              "/tmp/*": allow
+              "/private/tmp/*": allow
+              "<%= project %>/.maf/*": allow
+              "<%= project %>/.git/*": allow
+            task:
+              "*": deny
+              explore: allow
+          ---
+
+          <%= prompt %>
+        ERB
+
+        def models
+          return nil unless installed?
+
+          out, status = Open3.capture2("opencode", "models", err: File::NULL)
+          status.success? && !out.strip.empty? ? out.split : nil
+        rescue SystemCallError
+          nil
+        end
+
+        def wait = :watch
+
+        def vm_install = "curl -fsSL https://opencode.ai/install | bash"
+        AUTH = ".local/share/opencode/auth.json"
+        def vm_credentials = [Harness::VmCredential.file(File.join(Dir.home, AUTH), AUTH)]
+
+        def mcp
+          { file: ".maf/mcp/opencode.json", key: "mcp", schema: "https://opencode.ai/config.json",
+            entry: { "type" => "local", "command" => Harness::VAULT_MCP, "enabled" => true } }
+        end
+
+        def legacy_mcp_file = "opencode.json"
+        def bootstrap_dir = ".opencode"
+
+        PLUGIN = ".opencode/plugins/board-watch.js"
+
+        def runtime_hooks(worktree) = SetupAgent::RuntimeHooks.copy(worktree, "board-watch-opencode.js", PLUGIN)
+        def runtime_files = [PLUGIN]
+        def empty_dirs = [role_dir, File.dirname(PLUGIN), home_dir]
+
+        # An older maf tracked the role files and the plugin.
+        def untrack_paths(_root, tracked) = tracked.call(role_dir) + tracked.call(PLUGIN)
+
+        def launch_env = config_env(flow_file("mcp", "opencode.json"))
+        def run_env(config) = config_env(run_file(config, "mcp", "opencode.json"))
+        def config_env(file) = File.exist?(file) ? { "OPENCODE_CONFIG" => file } : {}
+
+        def launch(role, model)
+          ["opencode", ".", "--agent", role, "--prompt", "Start your work loop now.", *model_flag(model)]
+        end
+
+        # `opencode run --format json`. The result event shape is not verified,
+        # so the log shows no result text.
+        def build_command(config, prompt, session_id)
+          %w[opencode run --format json --agent] + [config.role] + model_flag(config.model, "-m") +
+            resume(session_id, "--session") + [prompt]
+        end
+
+        # DeepSeek costs twice as much at peak hours.
+        def peak_rate?(config) = configured_model(config).to_s.include?("deepseek")
+
+        # The model of a run in the opencode order: --model, the agent file, the project config, the user config.
+        CONFIG_MODEL = /^\s*"model"\s*:\s*"([^"]+)"/
+        AGENT_MODEL = /\A---\n(?:(?!^---$).)*?^model:\s*(\S+)/m
+
+        def configured_model(config)
+          config.model || find(File.join(role_dir, "#{config.role}.md"), AGENT_MODEL) ||
+            config_paths.lazy.filter_map { |path| find(path, CONFIG_MODEL) }.first
+        end
+
+        def config_paths
+          home = File.join(ENV.fetch("XDG_CONFIG_HOME", File.join(Dir.home, ".config")), "opencode")
+          %w[opencode.json opencode.jsonc] + %w[opencode.jsonc opencode.json].map { |name| File.join(home, name) }
+        end
+
+        def find(path, pattern) = File.exist?(path) ? File.read(path)[pattern, 1] : nil
+
+        # opencode prints terminal escape codes and can glue two JSON objects
+        # onto one line, so the session ID is matched on the start of an event
+        # object (captured from a real run), not by parsing whole lines.
+        EVENT_SESSION = /\{"type":"[\w.-]+","timestamp":\d+,"sessionID":"([^"]+)"/
+        # Each model call ends with a step_finish event. Its tokens.input
+        # excludes the cache reads and writes; reasoning is billed as output.
+        STEP_FINISH = /\{"type":"step_finish".*/
+
+        def stale_session?(output) = output.include?("Session not found")
+        def session_id(output) = output.scan(EVENT_SESSION).flatten.last
+
+        def steps(output)
+          output.scan(STEP_FINISH).filter_map { |json| Harness::Events.parse(json)&.dig("part", "tokens") }
+        end
+
+        def usage(output) = Harness::Usage.sum(steps(output).map { |tokens| Harness::Usage.normalize(flat(tokens)) })
+        def context(output) = steps(output).last&.then { |tokens| Harness::Usage.input(flat(tokens)) }
+
+        def flat(tokens)
+          { "input_tokens" => tokens["input"].to_i, "cache_read_input_tokens" => tokens.dig("cache", "read").to_i,
+            "cache_creation_input_tokens" => tokens.dig("cache", "write").to_i,
+            "output_tokens" => tokens["output"].to_i + tokens["reasoning"].to_i }
+        end
+
+        # opencode keeps its sessions in a SQLite database. The sqlite3 CLI reads it.
+        def database = File.join(Dir.home, ".local", "share", "opencode", "opencode.db")
+
+        def transcript_calls(id)
+          return [] unless File.exist?(database) && id.match?(/\A[\w-]+\z/)
+
+          out, status = Open3.capture2("sqlite3", "-readonly", "-json", database, transcript_query(id))
+          status.success? && !out.empty? ? JSON.parse(out).map(&:values) : []
+        rescue SystemCallError, JSON::ParserError
+          []
+        end
+
+        def transcript_query(id)
+          "select json_extract(data,'$.tool') tool, json_extract(data,'$.state.input.command') command, " \
+            "length(json_extract(data,'$.state.output')) size from part where session_id = '#{id}' " \
+            "and json_extract(data,'$.type') = 'tool'"
+        end
+      end
+    end
+  end
+end