agentboard 0.2.0

data/lib/agentboard/providers/claude_code.rb

@@ -0,0 +1,219 @@
+module Agentboard
+  module Providers
+    # Claude Code adapter.
+    #
+    # Passive: registers the AgentBoard MCP server in the project's `.mcp.json` and installs
+    # lifecycle hooks in `.claude/settings.local.json` (git-ignored by Claude Code), each
+    # running `agentboard hook ingest --provider claude --event <Event>`.
+    #
+    # Active: `claude -p --output-format stream-json --verbose` in the worktree with the
+    # prompt on stdin. Never enables `--dangerously-skip-permissions`; permission mode
+    # defaults to `acceptEdits` (file edits allowed, shell tools denied in print mode).
+    #
+    # Flags were checked against `claude --help` for the versions listed in
+    # compatibility/claude.yml. Hook payload fields follow Claude Code's documented hook input.
+    class ClaudeCode < Base
+      HOOK_EVENTS = %w[SessionStart UserPromptSubmit PreToolUse PostToolUse Notification Stop SubagentStop SessionEnd].freeze
+      HOOK_EVENT_MAP = {
+        "SessionStart" => "agent.session.started",
+        "UserPromptSubmit" => "agent.session.prompt_submitted",
+        "PreToolUse" => "agent.tool.started",
+        "PostToolUse" => "agent.tool.completed",
+        "Notification" => "agent.session.notification",
+        "Stop" => "agent.session.turn_completed",
+        "SubagentStop" => "agent.session.subagent_completed",
+        "SessionEnd" => "agent.session.ended"
+      }.freeze
+      # Only documented, low-sensitivity fields are retained from hook input.
+      HOOK_FIELDS = %w[session_id hook_event_name cwd tool_name source reason message stop_hook_active permission_mode].freeze
+      PERMISSION_MODES = %w[default acceptEdits plan].freeze
+
+      def self.key = :claude
+      def self.display_name = "Claude Code"
+      def self.binary = "claude"
+
+      def probe(environment: ENV)
+        path = which("claude")
+        return ProbeResult.new(provider: key, installed: false, supported_capabilities: [], validation: "not installed",
+                               diagnostics: [ "`claude` binary not found on PATH" ]) unless path
+
+        raw = run_version([ path, "--version" ])
+        version = raw.to_s[/\d+\.\d+\.\d+/]
+        all = %i[mcp passive_hooks active_execution structured_events streaming cancellation session_resume permission_requests]
+        caps, validation, diags = negotiate(version, all, safe_caps: %i[mcp passive_hooks])
+        ProbeResult.new(provider: key, installed: true, version: version, authenticated: nil,
+                        supported_capabilities: caps, validation: validation,
+                        diagnostics: diags + [ "Authentication is managed by Claude Code and is not inspected by AgentBoard." ])
+      end
+
+      # -- passive ---------------------------------------------------------------------
+      def mcp_entry(root:)
+        { "command" => "bundle", "args" => [ "exec", "agentboard", "mcp", "serve", "--root", root.to_s ], "env" => {} }
+      end
+
+      def hook_command(event)
+        %(cd "$CLAUDE_PROJECT_DIR" && bundle exec agentboard hook ingest --provider claude --event #{event})
+      end
+
+      def install_passive_hooks(project:, root:)
+        mcp_path = File.join(root, ".mcp.json")
+        settings_path = File.join(root, ".claude", "settings.local.json")
+        backups = [ ConfigEditor.backup!(mcp_path), ConfigEditor.backup!(settings_path) ].compact
+        changes = []
+
+        changes << ConfigEditor.merge_json!(mcp_path, %w[mcpServers agentboard], mcp_entry(root: root),
+                                            owned: ->(e) { e.is_a?(Hash) && Array(e["args"]).include?("agentboard") })
+
+        settings = ConfigEditor.read_json(settings_path)
+        settings["hooks"] ||= {}
+        added = []
+        HOOK_EVENTS.each do |event|
+          groups = (settings["hooks"][event] ||= [])
+          command = hook_command(event)
+          next if groups.any? { |g| Array(g["hooks"]).any? { |h| h["command"].to_s.include?("agentboard hook ingest") } }
+
+          groups << { "matcher" => "", "hooks" => [ { "type" => "command", "command" => command, "timeout" => 10 } ] }
+          added << event
+        end
+        ConfigEditor.write_json(settings_path, settings) if added.any?
+        changes << { path: settings_path, keys: [ "hooks" ], action: added.any? ? "added" : "unchanged", events: added }
+
+        manifest = { "provider" => key, "mcp" => { "path" => mcp_path, "keys" => %w[mcpServers agentboard] },
+                     "hooks" => { "path" => settings_path, "events" => HOOK_EVENTS } }
+        ConfigEditor.write_manifest!(root, key, manifest)
+        SetupResult.new(provider: key, changes: changes, manifest: manifest, backups: backups, warnings: [])
+      end
+
+      def remove_passive_hooks(project:, root:, manifest: nil)
+        manifest ||= ConfigEditor.read_manifest(root, key) || {}
+        removed = []
+        if (m = manifest["mcp"]) && ConfigEditor.delete_json!(m["path"], m["keys"])
+          removed << m["path"]
+        end
+        if (h = manifest["hooks"]) && File.exist?(h["path"])
+          settings = ConfigEditor.read_json(h["path"])
+          (settings["hooks"] || {}).each_value do |groups|
+            groups.each { |g| g["hooks"] = Array(g["hooks"]).reject { |x| x["command"].to_s.include?("agentboard hook ingest") } }
+            groups.reject! { |g| g["hooks"].empty? }
+          end
+          settings["hooks"]&.reject! { |_k, v| v.empty? }
+          settings.delete("hooks") if settings["hooks"] && settings["hooks"].empty?
+          ConfigEditor.write_json(h["path"], settings)
+          removed << h["path"]
+        end
+        removed
+      end
+
+      def parse_hook(event_name:, payload:)
+        data = payload.is_a?(Hash) ? payload : {}
+        name = data["hook_event_name"].presence || event_name.to_s
+        type = HOOK_EVENT_MAP.fetch(name, "agent.provider.unknown")
+        kept = data.slice(*HOOK_FIELDS)
+        if (input = data["tool_input"]).is_a?(Hash)
+          # Keep a target path for traceability; never retain full tool input (may hold secrets).
+          kept["target"] = (input["file_path"] || input["path"] || input["notebook_path"]).to_s[0, 500].presence
+          kept["command_excerpt"] = input["command"].to_s[0, 120].presence if data["tool_name"] == "Bash"
+        end
+        [ NormalizedEvent.build(type, kept.compact, external_session_id: data["session_id"]) ]
+      end
+
+      # -- active ----------------------------------------------------------------------
+      def launch_spec(execution:, worktree:, context_path:, prompt:)
+        config = execution.agent_profile&.config || {}
+        container = execution.metadata["isolation"] == "container"
+        # Inside the container the container is the security boundary (no host access, egress
+        # allowlist), so the agent may use tools without prompts. On the host it never can.
+        mode = config.fetch("permission_mode", container ? "bypassPermissions" : "acceptEdits").to_s
+        allowed_modes = container ? PERMISSION_MODES + %w[bypassPermissions] : PERMISSION_MODES
+        raise Error.policy_denied("Permission mode #{mode} is not allowed#{" outside a container" unless container}") unless allowed_modes.include?(mode)
+
+        argv = [ "claude", "-p", "--output-format", "stream-json", "--verbose", "--permission-mode", mode ]
+        argv += [ "--model", config["model"].to_s ] if config["model"].to_s.match?(/\A[\w.\-:]+\z/)
+        allowed = Array(config["allowed_tools"]).map(&:to_s).grep(/\A[\w()*:,. \-\/]+\z/)
+        argv += [ "--allowedTools", *allowed ] if allowed.any?
+        env = {}
+        if config.fetch("interactive_permissions", true) && !container
+          # Permission prompts are answered by a human through AgentBoard approvals: Claude calls
+          # the execution-bound AgentBoard MCP server, which blocks until a decision is made.
+          argv += [ "--mcp-config", JSON.generate("mcpServers" => { "agentboard" => permission_bridge(execution) }),
+                    "--strict-mcp-config", "--permission-prompt-tool", "mcp__agentboard__permission_prompt" ]
+          env["MCP_TOOL_TIMEOUT"] = ((Agentboard.config.runtime.fetch("permission_timeout_seconds", 600).to_i + 30) * 1000).to_s
+        end
+        LaunchSpec.new(argv: argv, env: env, stdin_data: prompt, chdir: worktree,
+                       passthrough_env: %w[ANTHROPIC_API_KEY CLAUDE_CODE_USE_BEDROCK CLAUDE_CODE_USE_VERTEX CLAUDE_CONFIG_DIR])
+      end
+
+      def permission_bridge(execution)
+        root = Agentboard.config.root_path.to_s
+        { "command" => RbConfig.ruby,
+          "args" => [ File.expand_path("../../../exe/agentboard", __dir__), "mcp", "serve", "--root", root, "--execution", execution.id, "--provider", "claude" ],
+          "env" => { "BUNDLE_GEMFILE" => File.join(root, "Gemfile"), "RUBYOPT" => "-rbundler/setup", "RAILS_ENV" => ENV.fetch("RAILS_ENV", "development") } }
+      end
+
+      def resume_spec(execution:, worktree:, input:)
+        sid = execution.metadata["provider_session_id"].to_s
+        raise UnsupportedCapability.new(:session_resume, provider: key) unless sid.match?(/\A[\w-]{8,}\z/) && supports?(:session_resume)
+
+        argv = [ "claude", "-p", "--output-format", "stream-json", "--verbose", "--resume", sid, "--permission-mode", "acceptEdits" ]
+        env = {}
+        if (execution.agent_profile&.config || {}).fetch("interactive_permissions", true)
+          argv += [ "--mcp-config", JSON.generate("mcpServers" => { "agentboard" => permission_bridge(execution) }),
+                    "--strict-mcp-config", "--permission-prompt-tool", "mcp__agentboard__permission_prompt" ]
+          env["MCP_TOOL_TIMEOUT"] = ((Agentboard.config.runtime.fetch("permission_timeout_seconds", 600).to_i + 30) * 1000).to_s
+        end
+        LaunchSpec.new(argv: argv, env: env, stdin_data: input.to_s, chdir: worktree, passthrough_env: %w[ANTHROPIC_API_KEY CLAUDE_CONFIG_DIR])
+      end
+
+      def parse_event(raw_event:)
+        data = safe_json(raw_event)
+        return [ NormalizedEvent.build("agent.execution.output", { "text" => raw_event.to_s.chomp[0, 4000] }) ] unless data.is_a?(Hash)
+
+        sid = data["session_id"]
+        case data["type"]
+        when "system"
+          if data["subtype"] == "init"
+            [ NormalizedEvent.build("agent.session.started", { "model" => data["model"], "cwd" => data["cwd"], "tools_count" => Array(data["tools"]).size }, external_session_id: sid) ]
+          else
+            [ NormalizedEvent.build("agent.provider.system", { "subtype" => data["subtype"].to_s[0, 64] }, external_session_id: sid) ]
+          end
+        when "assistant"
+          Array(data.dig("message", "content")).filter_map do |block|
+            case block["type"]
+            when "text" then NormalizedEvent.build("agent.execution.message", { "text" => block["text"].to_s[0, 8000] }, external_session_id: sid)
+            when "tool_use"
+              input = block["input"].is_a?(Hash) ? block["input"] : {}
+              NormalizedEvent.build("agent.tool.started", { "tool" => block["name"], "tool_use_id" => block["id"],
+                                                            "target" => (input["file_path"] || input["path"]).to_s[0, 500].presence }.compact, external_session_id: sid)
+            end
+            # "thinking" blocks are intentionally dropped: AgentBoard does not expose model reasoning.
+          end
+        when "user"
+          Array(data.dig("message", "content")).filter_map do |block|
+            next unless block["type"] == "tool_result"
+
+            NormalizedEvent.build("agent.tool.completed", { "tool_use_id" => block["tool_use_id"], "ok" => !block["is_error"] }, external_session_id: sid)
+          end
+        when "result"
+          usage = data["usage"].is_a?(Hash) ? data["usage"] : {}
+          events = []
+          Array(data["permission_denials"]).first(20).each do |d|
+            events << NormalizedEvent.build("agent.execution.permission_denied", { "tool" => d["tool_name"].to_s[0, 64] }, external_session_id: sid)
+          end
+          events << NormalizedEvent.build("agent.execution.usage", { "input_tokens" => usage["input_tokens"], "output_tokens" => usage["output_tokens"],
+                                                                    "reported_cost" => data["total_cost_usd"], "currency" => (data["total_cost_usd"] ? "USD" : nil),
+                                                                    "num_turns" => data["num_turns"] }.compact,
+                                          external_session_id: sid,
+                                          usage: Usage.new(input_tokens: usage["input_tokens"], output_tokens: usage["output_tokens"],
+                                                           reported_cost: data["total_cost_usd"], currency: data["total_cost_usd"] ? "USD" : nil,
+                                                           metering_kind: "unknown"))
+          ok = data["subtype"] == "success" && !data["is_error"]
+          events << NormalizedEvent.build("agent.execution.result", { "ok" => ok, "subtype" => data["subtype"], "summary" => data["result"].to_s[0, 4000] },
+                                          external_session_id: sid, terminal: true, status: ok ? "succeeded" : "failed")
+          events
+        else
+          [ NormalizedEvent.build("agent.provider.unknown", { "raw_type" => data["type"].to_s[0, 64] }, external_session_id: sid) ]
+        end
+      end
+    end
+  end
+end

data/lib/agentboard/providers/codex.rb

@@ -0,0 +1,177 @@
+module Agentboard
+  module Providers
+    # OpenAI Codex adapter.
+    #
+    # Passive: registers the MCP server through Codex's own interface
+    # (`codex mcp add agentboard -- bundle exec agentboard mcp serve --root ROOT`), so
+    # AgentBoard never rewrites ~/.codex/config.toml. Codex exposes no general lifecycle
+    # hooks to AgentBoard here, so passive tracking relies on explicit MCP activity and Git
+    # observation, labeled with provenance. MCP alone is not comprehensive tracking.
+    #
+    # Active: `codex exec --json --cd WORKTREE --sandbox workspace-write -` with the prompt
+    # on stdin. The App Server protocol is deliberately not used until fixture-backed tests
+    # exist for a pinned version (spec §26.3).
+    class Codex < Base
+      SANDBOXES = %w[read-only workspace-write].freeze
+
+      def self.key = :codex
+      def self.display_name = "OpenAI Codex"
+      def self.binary = "codex"
+
+      def probe(environment: ENV)
+        path = which("codex")
+        return ProbeResult.new(provider: key, installed: false, supported_capabilities: [], validation: "not installed",
+                               diagnostics: [ "`codex` binary not found on PATH" ]) unless path
+
+        version = run_version([ path, "--version" ]).to_s[/\d+\.\d+\.\d+/]
+        all = %i[mcp active_execution structured_events streaming cancellation session_resume]
+        caps, validation, diags = negotiate(version, all, safe_caps: %i[mcp])
+        ProbeResult.new(provider: key, installed: true, version: version, authenticated: nil, supported_capabilities: caps,
+                        validation: validation,
+                        diagnostics: diags + [ "Passive tracking for Codex is limited to MCP activity and Git observation." ])
+      end
+
+      def mcp_command(root:) = [ "bundle", "exec", "agentboard", "mcp", "serve", "--root", root.to_s ]
+
+      def config_toml_path = File.join(ENV.fetch("CODEX_HOME", File.join(Dir.home, ".codex")), "config.toml")
+
+      # Codex calls the `notify` program with a JSON argument after each agent turn. It is a
+      # global, top-level key, so AgentBoard only adds it when explicitly requested and when no
+      # other notify program is configured; the managed block is removed by `provider remove`.
+      def notify_command(root)
+        [ "/usr/bin/env", "BUNDLE_GEMFILE=#{File.join(root, "Gemfile")}", RbConfig.ruby, "-rbundler/setup",
+          File.expand_path("../../../exe/agentboard", __dir__), "hook", "ingest", "--provider", "codex", "--event", "agent-turn-complete", "--root", root.to_s ]
+      end
+
+      def install_notify!(root)
+        path = config_toml_path
+        content = File.exist?(path) ? File.read(path) : ""
+        top_level = content.split(/^\s*\[/, 2).first.to_s
+        if top_level.match?(/^\s*notify\s*=/) && !content.include?(ConfigEditor::MARK_BEGIN)
+          return [ { path: path, action: "skipped", reason: "an existing notify program is configured" }, nil ]
+        end
+
+        backup = ConfigEditor.backup!(path)
+        change = ConfigEditor.upsert_block!(path, "notify = #{JSON.generate(notify_command(root))}", position: :start)
+        [ change, backup ]
+      end
+
+      def install_passive_hooks(project:, root:, notify: false)
+        path = which("codex") or raise Error.provider_unavailable("codex binary not found")
+        list_out, _e, _s = Open3.capture3(Subprocess.scrubbed_env, path, "mcp", "list")
+        if list_out.to_s.match?(/^\s*agentboard\b/)
+          changes = [ { path: "codex mcp", keys: [ "agentboard" ], action: "unchanged" } ]
+        else
+          out, err, st = Open3.capture3(Subprocess.scrubbed_env, path, "mcp", "add", "agentboard", "--", *mcp_command(root: root))
+          raise Error.provider_unavailable("codex mcp add failed: #{Redactor.redact(err.presence || out)[0, 300]}") unless st.success?
+
+          changes = [ { path: "codex mcp", keys: [ "agentboard" ], action: "added", command: mcp_command(root: root).join(" ") } ]
+        end
+        backups = []
+        warnings = []
+        if notify
+          change, backup = install_notify!(root)
+          changes << change
+          backups << backup if backup
+        else
+          warnings << "Codex notify hook not installed (pass --notify); activity is tracked through MCP calls and Git evidence."
+        end
+        manifest = { "provider" => key, "codex_mcp_name" => "agentboard", "notify_config" => (notify ? config_toml_path : nil) }.compact
+        ConfigEditor.write_manifest!(root, key, manifest)
+        SetupResult.new(provider: key, changes: changes, manifest: manifest, backups: backups, warnings: warnings)
+      end
+
+      def remove_passive_hooks(project:, root:, manifest: nil)
+        removed = []
+        manifest ||= ConfigEditor.read_manifest(root, key) || {}
+        removed << manifest["notify_config"] if manifest["notify_config"] && ConfigEditor.remove_block!(manifest["notify_config"])
+        if (path = which("codex"))
+          _o, _e, st = Open3.capture3(Subprocess.scrubbed_env, path, "mcp", "remove", "agentboard")
+          removed << "codex mcp agentboard" if st.success?
+        end
+        removed
+      end
+
+      # Hook-style payloads (e.g. from a `notify` program) are accepted if an operator wires one.
+      def parse_hook(event_name:, payload:)
+        data = payload.is_a?(Hash) ? payload : {}
+        type = data["type"] == "agent-turn-complete" ? "agent.session.turn_completed" : "agent.provider.unknown"
+        summary = data["last-assistant-message"].to_s[0, 500].presence
+        [ NormalizedEvent.build(type, { "cwd" => data["cwd"], "turn_id" => data["turn-id"], "summary" => summary }.compact,
+                                external_session_id: data["thread-id"]) ]
+      end
+
+      def launch_spec(execution:, worktree:, context_path:, prompt:)
+        config = execution.agent_profile&.config || {}
+        container = execution.metadata["isolation"] == "container"
+        # Codex's own sandbox (Seatbelt/Landlock) is unavailable inside Docker; the container is the boundary.
+        sandbox = config.fetch("sandbox", container ? "danger-full-access" : "workspace-write").to_s
+        allowed = container ? SANDBOXES + %w[danger-full-access] : SANDBOXES
+        raise Error.policy_denied("Codex sandbox #{sandbox} is not allowed#{" outside a container" unless container}") unless allowed.include?(sandbox)
+
+        argv = [ "codex", "exec", "--json", "--cd", worktree.to_s, "--sandbox", sandbox, "--skip-git-repo-check" ]
+        argv += [ "--model", config["model"].to_s ] if config["model"].to_s.match?(/\A[\w.\-:]+\z/)
+        argv << "-"
+        # `codex exec` authenticates API keys via CODEX_API_KEY; map it from OPENAI_API_KEY.
+        LaunchSpec.new(argv: argv, env: {}, stdin_data: prompt, chdir: worktree, passthrough_env: %w[OPENAI_API_KEY CODEX_API_KEY CODEX_HOME],
+                       credential_aliases: container ? { "CODEX_API_KEY" => "OPENAI_API_KEY" } : nil)
+      end
+
+      def resume_spec(execution:, worktree:, input:)
+        tid = execution.metadata["provider_session_id"].to_s
+        raise UnsupportedCapability.new(:session_resume, provider: key) unless tid.match?(/\A[\w-]{8,}\z/) && supports?(:session_resume)
+
+        LaunchSpec.new(argv: [ "codex", "exec", "--json", "--cd", worktree.to_s, "resume", tid, "-" ], env: {}, stdin_data: input.to_s,
+                       chdir: worktree, passthrough_env: %w[OPENAI_API_KEY CODEX_HOME])
+      end
+
+      def parse_event(raw_event:)
+        data = safe_json(raw_event)
+        return [ NormalizedEvent.build("agent.execution.output", { "text" => raw_event.to_s.chomp[0, 4000] }) ] unless data.is_a?(Hash)
+
+        case data["type"]
+        when "thread.started" then [ NormalizedEvent.build("agent.session.started", {}, external_session_id: data["thread_id"]) ]
+        when "turn.started" then [ NormalizedEvent.build("agent.execution.turn_started", {}) ]
+        when "item.started", "item.updated", "item.completed" then parse_item(data)
+        when "turn.completed"
+          u = data["usage"].is_a?(Hash) ? data["usage"] : {}
+          [ NormalizedEvent.build("agent.execution.usage", u.slice("input_tokens", "cached_input_tokens", "output_tokens"),
+                                  usage: Usage.new(input_tokens: u["input_tokens"], output_tokens: u["output_tokens"], metering_kind: "unknown")),
+            NormalizedEvent.build("agent.execution.result", { "ok" => true }, terminal: true, status: "succeeded") ]
+        when "turn.failed"
+          [ NormalizedEvent.build("agent.execution.result", { "ok" => false, "error" => data.dig("error", "message").to_s[0, 2000] }, terminal: true, status: "failed") ]
+        when "error"
+          [ NormalizedEvent.build("agent.execution.error", { "message" => data["message"].to_s[0, 2000] }) ]
+        else
+          [ NormalizedEvent.build("agent.provider.unknown", { "raw_type" => data["type"].to_s[0, 64] }) ]
+        end
+      end
+
+      private
+
+      def parse_item(data)
+        item = data["item"].is_a?(Hash) ? data["item"] : {}
+        done = data["type"] == "item.completed"
+        case item["type"]
+        when "agent_message"
+          done ? [ NormalizedEvent.build("agent.execution.message", { "text" => item["text"].to_s[0, 8000] }) ] : []
+        when "reasoning" then [] # private model reasoning is never surfaced
+        when "command_execution"
+          payload = { "tool" => "shell", "command_excerpt" => item["command"].to_s[0, 160], "exit_code" => item["exit_code"], "status" => item["status"] }.compact
+          [ NormalizedEvent.build(done ? "agent.tool.completed" : "agent.tool.started", payload) ]
+        when "file_change"
+          files = Array(item["changes"]).map { |c| c["path"].to_s[0, 300] }.first(50)
+          [ NormalizedEvent.build("agent.tool.completed", { "tool" => "file_change", "files" => files, "status" => item["status"] }.compact) ]
+        when "mcp_tool_call"
+          [ NormalizedEvent.build(done ? "agent.tool.completed" : "agent.tool.started", { "tool" => "mcp:#{item["server"]}/#{item["tool"]}" }) ]
+        when "error"
+          done ? [ NormalizedEvent.build("agent.execution.error", { "message" => item["message"].to_s[0, 2000] }) ] : []
+        when "todo_list", "web_search"
+          [ NormalizedEvent.build("agent.execution.activity", { "kind" => item["type"] }) ]
+        else
+          [ NormalizedEvent.build("agent.provider.unknown", { "raw_type" => "item:#{item["type"]}".to_s[0, 64] }) ]
+        end
+      end
+    end
+  end
+end

data/lib/agentboard/providers/compatibility/claude.yml

@@ -0,0 +1,13 @@
+# Provider compatibility manifest (spec §26.5).
+# status:
+#   smoke_tested  – real end-to-end run through AgentBoard (worktree → stream → snapshot →
+#                   verification → review) passed; sanitized real output kept as a fixture
+#   flags_checked – CLI flags verified against `--help`; parsing covered by fixtures only
+provider: claude
+adapter_version: 1
+validated:
+  - binary_version: "2.1.325"
+    status: smoke_tested
+    smoke_test: "2026-11-14 · haiku · implement ticket in Rails app · checks passed at snapshot SHA"
+    capabilities: [mcp, passive_hooks, active_execution, structured_events, streaming, cancellation, session_resume, permission_requests]
+    fixtures: test/fixtures/providers/claude_code

data/lib/agentboard/providers/compatibility/codex.yml

@@ -0,0 +1,10 @@
+provider: codex
+adapter_version: 1
+validated:
+  - binary_version: "0.156.1"
+    status: flags_checked
+    # Real `codex exec --json` output captured; the run was rejected by the account's model
+    # policy (model_not_found), so only the failure path is validated against real output.
+    real_fixtures: [test/fixtures/providers/codex/real_0.156.1_model_rejected.jsonl]
+    capabilities: [mcp, active_execution, structured_events, streaming, cancellation]
+    fixtures: test/fixtures/providers/codex

data/lib/agentboard/providers/config_editor.rb

@@ -0,0 +1,106 @@
+module Agentboard
+  module Providers
+    # Minimal, reversible edits to provider configuration files (spec §31.2):
+    # back up first, change only AgentBoard-owned entries, never replace a whole file,
+    # and record a manifest so `provider remove` can undo exactly what was added.
+    module ConfigEditor
+      MARK_BEGIN = "# >>> agentboard (managed block — do not edit) >>>".freeze
+      MARK_END = "# <<< agentboard <<<".freeze
+
+      module_function
+
+      def backup!(path)
+        return nil unless File.exist?(path)
+
+        dest = "#{path}.agentboard-backup-#{Time.now.utc.strftime("%Y%m%d%H%M%S")}"
+        FileUtils.cp(path, dest, preserve: true)
+        dest
+      end
+
+      def read_json(path)
+        return {} unless File.exist?(path)
+
+        data = JSON.parse(File.read(path))
+        raise Error.validation_failed("#{path} must contain a JSON object") unless data.is_a?(Hash)
+
+        data
+      rescue JSON::ParserError => e
+        raise Error.validation_failed("#{path} is not valid JSON (#{e.message[0, 80]}); refusing to modify it")
+      end
+
+      def write_json(path, data)
+        FileUtils.mkdir_p(File.dirname(path))
+        tmp = "#{path}.tmp-#{Process.pid}"
+        File.write(tmp, JSON.pretty_generate(data) + "\n")
+        File.rename(tmp, path)
+      end
+
+      # Sets data[*keys] = value only if absent or already AgentBoard-owned. Returns change hash.
+      def merge_json!(path, keys, value, owned: ->(existing) { existing == value })
+        data = read_json(path)
+        parent = keys[0..-2].reduce(data) { |h, k| h[k] ||= {} }
+        existing = parent[keys.last]
+        return { path: path, keys: keys, action: "unchanged" } if existing == value
+        if existing && !owned.call(existing)
+          return { path: path, keys: keys, action: "skipped", reason: "an existing non-AgentBoard entry is present" }
+        end
+
+        parent[keys.last] = value
+        write_json(path, data)
+        { path: path, keys: keys, action: existing ? "updated" : "added" }
+      end
+
+      def delete_json!(path, keys)
+        data = read_json(path)
+        parent = keys[0..-2].reduce(data) { |h, k| h.is_a?(Hash) ? h[k] : nil }
+        return false unless parent.is_a?(Hash) && parent.key?(keys.last)
+
+        parent.delete(keys.last)
+        write_json(path, data)
+        true
+      end
+
+      # Inserts/replaces a marked text block (used for TOML where no parser is bundled).
+      def upsert_block!(path, body, position: :end)
+        content = File.exist?(path) ? File.read(path) : +""
+        block = "#{MARK_BEGIN}\n#{body.strip}\n#{MARK_END}\n"
+        if content.include?(MARK_BEGIN)
+          new_content = content.sub(/#{Regexp.escape(MARK_BEGIN)}.*?#{Regexp.escape(MARK_END)}\n?/m, block)
+          action = new_content == content ? "unchanged" : "updated"
+        else
+          new_content = position == :start ? block + "\n" + content : content + (content.end_with?("\n") || content.empty? ? "" : "\n") + "\n" + block
+          action = "added"
+        end
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, new_content) unless action == "unchanged"
+        { path: path, action: action }
+      end
+
+      def remove_block!(path)
+        return false unless File.exist?(path)
+
+        content = File.read(path)
+        new_content = content.sub(/\n?#{Regexp.escape(MARK_BEGIN)}.*?#{Regexp.escape(MARK_END)}\n?/m, "\n")
+        return false if new_content == content
+
+        File.write(path, new_content)
+        true
+      end
+
+      def manifest_path(root, provider) = File.join(root.to_s, ".agentboard", "manifests", "#{provider}.json")
+
+      def write_manifest!(root, provider, manifest)
+        path = manifest_path(root, provider)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, JSON.pretty_generate(manifest.merge("written_at" => Time.now.utc.iso8601)))
+        path
+      end
+
+      def read_manifest(root, provider)
+        path = manifest_path(root, provider)
+        File.exist?(path) ? JSON.parse(File.read(path)) : nil
+      end
+    end
+  end
+end
+require "fileutils"

data/lib/agentboard/providers/cursor.rb

@@ -0,0 +1,40 @@
+module Agentboard
+  module Providers
+    # Cursor: passive-first (spec §26.4). Registers the MCP server in `.cursor/mcp.json`.
+    # Active launch/resume stay disabled until a tested provider interface exists.
+    class Cursor < Base
+      def self.key = :cursor
+      def self.display_name = "Cursor"
+
+      def probe(environment: ENV)
+        bin = which("cursor-agent") || which("cursor")
+        version = bin && run_version([ bin, "--version" ]).to_s[/\d+\.\d+\.\d+/]
+        ProbeResult.new(provider: key, installed: !bin.nil?, version: version, authenticated: nil,
+                        supported_capabilities: %i[mcp], validation: bin ? "passive only" : "not installed",
+                        diagnostics: [ "Cursor active execution is not enabled: no fixture-validated agent interface." ])
+      end
+
+      def install_passive_hooks(project:, root:)
+        path = File.join(root, ".cursor", "mcp.json")
+        backups = [ ConfigEditor.backup!(path) ].compact
+        entry = { "command" => "bundle", "args" => [ "exec", "agentboard", "mcp", "serve", "--root", root.to_s ] }
+        change = ConfigEditor.merge_json!(path, %w[mcpServers agentboard], entry, owned: ->(e) { e.is_a?(Hash) && Array(e["args"]).include?("agentboard") })
+        manifest = { "provider" => key, "mcp" => { "path" => path, "keys" => %w[mcpServers agentboard] } }
+        ConfigEditor.write_manifest!(root, key, manifest)
+        SetupResult.new(provider: key, changes: [ change ], manifest: manifest, backups: backups, warnings: [ "Cursor hooks are not installed." ])
+      end
+
+      def remove_passive_hooks(project:, root:, manifest: nil)
+        m = (manifest || ConfigEditor.read_manifest(root, key) || {})["mcp"]
+        m && ConfigEditor.delete_json!(m["path"], m["keys"]) ? [ m["path"] ] : []
+      end
+
+      def parse_hook(event_name:, payload:)
+        [ NormalizedEvent.build("agent.provider.unknown", { "event" => event_name.to_s[0, 64] }) ]
+      end
+
+      def launch_spec(**) = raise(UnsupportedCapability.new(:active_execution, provider: key))
+      def parse_event(raw_event:) = [ NormalizedEvent.build("agent.execution.output", { "text" => raw_event.to_s[0, 4000] }) ]
+    end
+  end
+end

data/lib/agentboard/providers/fake.rb

@@ -0,0 +1,59 @@
+require "rbconfig"
+
+module Agentboard
+  module Providers
+    # Deterministic provider for tests and demos (spec §35.3.4). It launches a small Ruby
+    # script that emits JSONL events and edits files in the worktree. Never calls a paid API.
+    #
+    # Scenarios (profile config `scenario`): success, fail, slow, permission, secret, malformed, noop
+    class Fake < Base
+      SCRIPT = File.expand_path("fake_agent_script.rb", __dir__)
+
+      def self.key = :fake
+      def self.display_name = "Fake agent (testing)"
+
+      def probe(environment: ENV)
+        ProbeResult.new(provider: key, installed: true, version: "fake-#{Agentboard::VERSION}", authenticated: true,
+                        supported_capabilities: CAPABILITIES - [ :passive_hooks ], validation: "built-in", diagnostics: [])
+      end
+
+      def launch_spec(execution:, worktree:, context_path:, prompt:)
+        scenario = (execution.agent_profile&.config || {}).fetch("scenario", execution.metadata["scenario"] || "success").to_s
+        raise Error.validation_failed("Unknown fake scenario") unless scenario.match?(/\A[a-z_]+\z/)
+
+        container = execution.metadata["isolation"] == "container"
+        LaunchSpec.new(argv: [ container ? "ruby" : RbConfig.ruby, SCRIPT, "--scenario", scenario ],
+                       env: { "AGENTBOARD_TICKET" => execution.ticket.key }, stdin_data: prompt, chdir: worktree,
+                       mounts: container ? [ File.dirname(SCRIPT) ] : nil)
+      end
+
+      def resume_spec(execution:, worktree:, input:)
+        sid = execution.metadata["provider_session_id"].to_s
+        raise UnsupportedCapability.new(:session_resume, provider: key) unless sid.start_with?("fake-")
+
+        LaunchSpec.new(argv: [ RbConfig.ruby, SCRIPT, "--scenario", "resume", "--session", sid ],
+                       env: { "AGENTBOARD_TICKET" => execution.ticket.key }, stdin_data: input.to_s, chdir: worktree)
+      end
+
+      def parse_event(raw_event:)
+        data = safe_json(raw_event)
+        return [ NormalizedEvent.build("agent.execution.output", { "text" => raw_event.to_s.chomp[0, 4000] }) ] unless data.is_a?(Hash)
+
+        case data["type"]
+        when "session" then [ NormalizedEvent.build("agent.session.started", data.slice("model"), external_session_id: data["session_id"]) ]
+        when "message" then [ NormalizedEvent.build("agent.execution.message", { "text" => data["text"].to_s[0, 8000] }) ]
+        when "tool_start" then [ NormalizedEvent.build("agent.tool.started", data.slice("tool", "target")) ]
+        when "tool_end" then [ NormalizedEvent.build("agent.tool.completed", data.slice("tool", "target", "ok")) ]
+        when "permission" then [ NormalizedEvent.build("agent.execution.permission_requested", data.slice("tool", "reason"), status: "waiting_for_permission") ]
+        when "usage"
+          [ NormalizedEvent.build("agent.execution.usage", data.slice("input_tokens", "output_tokens"),
+                                  usage: Usage.new(input_tokens: data["input_tokens"], output_tokens: data["output_tokens"], metering_kind: "unknown")) ]
+        when "result"
+          [ NormalizedEvent.build("agent.execution.result", data.slice("ok", "summary"), terminal: true, status: data["ok"] ? "succeeded" : "failed") ]
+        else
+          [ NormalizedEvent.build("agent.provider.unknown", { "raw_type" => data["type"].to_s[0, 64] }) ]
+        end
+      end
+    end
+  end
+end