agentboard 0.2.0

data/lib/agentboard/event_schema.rb

@@ -0,0 +1,37 @@
+module Agentboard
+  # Versioned event payloads (spec §11, §23.4). Historical events are never rewritten:
+  # readers call `EventSchema.upcast` to see old payloads in the current shape.
+  #
+  #   EventSchema.register("agent.execution.usage", from: 1) { |p| … returns v2 payload … }
+  module EventSchema
+    @current = Hash.new(1)
+    @upcasters = {}
+
+    class << self
+      def current_version(type) = @current[type.to_s]
+
+      def register(type, from:, &block)
+        @upcasters[[ type.to_s, from ]] = block
+        @current[type.to_s] = [ @current[type.to_s], from + 1 ].max
+      end
+
+      # Applies successive upcasters from `version` to the current version.
+      def upcast(type, version, payload)
+        version = version.to_i
+        data = payload.is_a?(Hash) ? payload.dup : {}
+        while version < current_version(type)
+          step = @upcasters[[ type.to_s, version ]] or break
+          data = step.call(data)
+          version += 1
+        end
+        data
+      end
+    end
+
+    # v2 (AgentBoard 0.2): monetary amounts carry an explicit currency; unknown stays nil.
+    register("agent.execution.usage", from: 1) do |p|
+      usd = p.delete("reported_cost_usd")
+      p.merge("reported_cost" => usd, "currency" => usd.nil? ? nil : "USD")
+    end
+  end
+end

data/lib/agentboard/extensions.rb

@@ -0,0 +1,58 @@
+module Agentboard
+  # Open-core extension points (spec §16). The MIT core works fully offline for a single
+  # local user. Commercial extensions (agentboard-pro) register here and unlock features
+  # according to their own licence; the core never phones home or needs an account.
+  module Extensions
+    FEATURES = {
+      team_mode: "Team mode: host-app authentication, roles and separation of duties",
+      advanced_workflows: "Advanced workflows: conditions, retries, per-step timeouts, external and pull-request steps",
+      governance: "Analytics & governance: operational metrics, support bundle, scheduled retention, audit export",
+      capture: "Capture widget beyond development (team use on staging) and region screenshots",
+      git_hosting: "Git hosting integrations (GitHub, GitLab, Bitbucket): signed webhooks, merge-aware completion, pull-request creation"
+    }.freeze
+
+    Extension = Struct.new(:name, :version, :features, :status, keyword_init: true) do
+      def enabled_features = Array(features.respond_to?(:call) ? features.call : features).map(&:to_sym)
+      def status_info = status.respond_to?(:call) ? status.call : status
+    end
+
+    @extensions = {}
+    @hooks = Hash.new { |h, k| h[k] = [] }
+    @step_handlers = {}
+
+    class << self
+      attr_reader :extensions, :step_handlers
+
+      def register(name, version:, features:, status: nil)
+        @extensions[name.to_s] = Extension.new(name: name.to_s, version: version, features: features, status: status)
+      end
+
+      def unregister(name) = @extensions.delete(name.to_s)
+
+      def feature?(key) = @extensions.values.any? { |e| e.enabled_features.include?(key.to_sym) }
+
+      def require!(key)
+        return true if feature?(key)
+
+        raise Error.policy_denied("#{FEATURES.fetch(key.to_sym)} requires AgentBoard Pro with a valid licence", feature: key.to_s)
+      end
+
+      # Hooks: on(:event) { |*args| … }; run(:event, *args) calls every subscriber.
+      def on(event, &block) = (@hooks[event.to_sym] << block)
+      def run(event, *args, **kwargs) = @hooks[event.to_sym].map { |h| h.call(*args, **kwargs) }
+      def hooks?(event) = @hooks[event.to_sym].any?
+
+      # Workflow step types provided by extensions.
+      def register_step_handler(type, &block) = (@step_handlers[type.to_s] = block)
+      def step_handler(type) = @step_handlers[type.to_s]
+
+      def reset_hooks!
+        @hooks.clear
+        @step_handlers.clear
+      end
+    end
+  end
+
+  def self.feature?(key) = Extensions.feature?(key)
+  def self.require_feature!(key) = Extensions.require!(key)
+end

data/lib/agentboard/git/repository.rb

@@ -0,0 +1,92 @@
+module Agentboard
+  module Git
+    # Thin, argv-only wrapper over the git CLI. Never interpolates into a shell.
+    class Repository
+      class CommandFailed < StandardError; end
+
+      attr_reader :root
+
+      def initialize(root)
+        @root = File.expand_path(root.to_s)
+      end
+
+      def git(*args, chdir: root, allow_failure: false, env: {})
+        out, err, status = Open3.capture3(safe_env.merge(env), "git", *args.map(&:to_s), chdir: chdir)
+        unless status.success? || allow_failure
+          raise CommandFailed, "git #{args.first} failed: #{Redactor.redact(err.strip)[0, 500]}"
+        end
+
+        allow_failure ? [ out, err, status ] : out
+      end
+
+      def repository? = git("rev-parse", "--is-inside-work-tree", allow_failure: true)[2].success?
+      def toplevel = git("rev-parse", "--show-toplevel").strip
+      def head_sha(chdir: root) = git("rev-parse", "HEAD", chdir: chdir).strip
+      def current_branch(chdir: root) = git("rev-parse", "--abbrev-ref", "HEAD", chdir: chdir).strip
+
+      def default_branch
+        out, _e, st = git("symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD", allow_failure: true)
+        return out.strip.sub(%r{\Aorigin/}, "") if st.success? && out.present?
+
+        %w[main master trunk].find { |b| git("rev-parse", "--verify", "--quiet", "refs/heads/#{b}", allow_failure: true)[2].success? } || current_branch
+      rescue CommandFailed
+        "main"
+      end
+
+      def clean?(chdir: root) = git("status", "--porcelain", chdir: chdir).strip.empty?
+
+      # Returns the full SHA if the object exists as a commit in this repository.
+      def resolve_commit(sha)
+        return nil unless sha.to_s.match?(/\A[0-9a-fA-F]{4,64}\z/)
+
+        out, _e, st = git("rev-parse", "--verify", "--quiet", "#{sha}^{commit}", allow_failure: true)
+        st.success? ? out.strip : nil
+      end
+
+      def commit_subject(sha) = git("log", "-1", "--format=%s", sha).strip
+      def ancestor?(ancestor, descendant) = git("merge-base", "--is-ancestor", ancestor, descendant, allow_failure: true)[2].success?
+
+      def tracked_files(chdir: root) = git("ls-files", "-z", chdir: chdir).split("\0")
+
+      def changed_files(base, head, chdir: root)
+        git("diff", "--name-only", "-z", "#{base}..#{head}", chdir: chdir).split("\0")
+      end
+
+      def diff_stat(base, head, chdir: root)
+        out = git("diff", "--shortstat", "#{base}..#{head}", chdir: chdir)
+        {
+          files: out[/(\d+) files? changed/, 1].to_i,
+          insertions: out[/(\d+) insertions?/, 1].to_i,
+          deletions: out[/(\d+) deletions?/, 1].to_i
+        }
+      end
+
+      def log(limit: 20, chdir: root, range: nil)
+        args = [ "log", "-#{limit.to_i}", "--format=%H%x1f%an%x1f%aI%x1f%s" ]
+        args << range if range
+        git(*args, chdir: chdir).lines.map do |line|
+          sha, author, date, subject = line.chomp.split("\x1f", 4)
+          { sha: sha, author: author, date: date, subject: subject }
+        end
+      rescue CommandFailed
+        []
+      end
+
+      def worktrees
+        git("worktree", "list", "--porcelain").split("\n\n").map do |block|
+          block.lines.each_with_object({}) do |line, h|
+            k, v = line.chomp.split(" ", 2)
+            h[k] = v || true
+          end
+        end
+      end
+
+      private
+
+      # Prevent user/global hooks or pagers from altering behaviour.
+      def safe_env
+        { "GIT_TERMINAL_PROMPT" => "0", "GIT_PAGER" => "cat", "LC_ALL" => "C" }
+      end
+    end
+  end
+end

data/lib/agentboard/git/worktree_manager.rb

@@ -0,0 +1,107 @@
+module Agentboard
+  module Git
+    # Creates one dedicated branch + worktree per execution (spec §8, §29.2):
+    #   .agentboard/worktrees/AB-142-exec-001   on branch agentboard/AB-142/exec-001
+    # Worktrees are source-control isolation only — they are NOT security sandboxes.
+    class WorktreeManager
+      Worktree = Struct.new(:path, :branch, :base_sha, keyword_init: true)
+
+      attr_reader :repository, :workspace
+
+      def initialize(repository:, workspace:)
+        @repository = repository
+        @workspace = File.expand_path(workspace.to_s)
+      end
+
+      def self.name_for(ticket_key, attempt)
+        raise Error.validation_failed("Invalid ticket key") unless ticket_key.to_s.match?(/\A[A-Z][A-Z0-9_-]*-\d+\z/)
+
+        suffix = "exec-#{attempt.to_i.to_s.rjust(3, "0")}"
+        [ "#{ticket_key}-#{suffix}", "agentboard/#{ticket_key}/#{suffix}" ]
+      end
+
+      def create!(ticket_key:, attempt:, base_ref: "HEAD")
+        dir_name, branch = self.class.name_for(ticket_key, attempt)
+        FileUtils.mkdir_p(workspace, mode: 0o700)
+        ensure_ignored!
+        path = PathGuard.within!(workspace, dir_name)
+        raise Error.workspace_conflict("Worktree #{dir_name} already exists") if File.exist?(path)
+
+        base_sha = repository.git("rev-parse", "--verify", "#{base_ref}^{commit}").strip
+        repository.git("worktree", "add", "-b", branch, path, base_sha)
+        Worktree.new(path: path, branch: branch, base_sha: base_sha)
+      rescue Repository::CommandFailed => e
+        raise Error.workspace_conflict(e.message)
+      end
+
+      def head_sha(path) = repository.head_sha(chdir: guard(path))
+      def clean?(path) = repository.clean?(chdir: guard(path))
+
+      # Commits any pending work in the worktree on behalf of the execution, so the result is
+      # bound to an immutable SHA. Returns the new head.
+      def snapshot!(path, message:)
+        dir = guard(path)
+        return head_sha(dir) if repository.clean?(chdir: dir)
+
+        repository.git("add", "-A", chdir: dir)
+        repository.git("-c", "user.name=AgentBoard", "-c", "user.email=agentboard@localhost", "commit", "--no-verify", "-m", message, chdir: dir)
+        head_sha(dir)
+      end
+
+      def changes(path, base_sha)
+        dir = guard(path)
+        head = head_sha(dir)
+        { head_sha: head, files: repository.changed_files(base_sha, head, chdir: dir), stat: repository.diff_stat(base_sha, head, chdir: dir) }
+      end
+
+      # Removal requires: no uncommitted changes unless force (explicit confirmation).
+      def remove!(path, force: false, delete_branch: false)
+        dir = guard(path)
+        return false unless File.directory?(dir)
+        if !force && !repository.clean?(chdir: dir)
+          raise Error.workspace_conflict("Worktree has uncommitted changes; confirm with --force")
+        end
+
+        branch = repository.current_branch(chdir: dir)
+        args = [ "worktree", "remove" ]
+        args << "--force" if force
+        repository.git(*args, dir)
+        repository.git("branch", "-D", branch, allow_failure: true) if delete_branch && branch.start_with?("agentboard/")
+        true
+      end
+
+      def prune! = repository.git("worktree", "prune")
+
+      def list
+        # Compare real paths: on macOS /var and /tmp are symlinks into /private.
+        real = File.exist?(workspace) ? File.realpath(workspace) : workspace
+        repository.worktrees.select { |w| w["worktree"].to_s.start_with?(real) || w["worktree"].to_s.start_with?(workspace) }
+      end
+
+      private
+
+      def guard(path) = PathGuard.within!(workspace, path)
+
+      def ensure_ignored!
+        exclude = File.join(repository.git("rev-parse", "--git-common-dir").strip.then { |d| File.expand_path(d, repository.root) }, "info", "exclude")
+        top = File.realpath(repository.toplevel)
+        ws = File.realpath(workspace)
+        return unless ws.start_with?(top + "/") # workspace outside repo
+        rel = ws.delete_prefix(top + "/")
+
+        # Local AgentBoard state never shows up as untracked files in the main checkout.
+        wanted = [ "/#{rel}/" ]
+        state_dir = File.dirname(ws)
+        if File.basename(state_dir) == ".agentboard"
+          base = state_dir.delete_prefix(top + "/")
+          wanted += %w[logs cache spool manifests].map { |d| "/#{base}/#{d}/" }
+        end
+        FileUtils.mkdir_p(File.dirname(exclude))
+        lines = File.exist?(exclude) ? File.read(exclude).lines.map(&:strip) : []
+        missing = wanted - lines
+        File.open(exclude, "a") { |f| missing.each { |l| f.puts(l) } } if missing.any?
+      end
+    end
+  end
+end
+require "fileutils"

data/lib/agentboard/git.rb

@@ -0,0 +1,4 @@
+require "open3"
+require "agentboard/git/repository"
+require "agentboard/git/worktree_manager"
+require "agentboard/path_guard"

data/lib/agentboard/ids.rb

@@ -0,0 +1,33 @@
+module Agentboard
+  # Application-generated identifiers. UUIDv7 is time-ordered, portable across
+  # PostgreSQL and SQLite, and safe to generate outside the database (spec §23.1).
+  module Ids
+    module_function
+
+    def uuid = SecureRandom.uuid_v7
+    def correlation = "c-#{SecureRandom.hex(8)}"
+    def token(bytes = 32) = SecureRandom.urlsafe_base64(bytes)
+    def digest(value) = Digest::SHA256.hexdigest(value.to_s)
+
+    # Constant-time comparison of a presented secret with a stored digest.
+    def secure_match?(presented, stored_digest)
+      return false if presented.nil? || stored_digest.nil?
+
+      a = digest(presented)
+      a.bytesize == stored_digest.bytesize && OpenSSL.fixed_length_secure_compare(a, stored_digest)
+    end
+
+    # Canonical JSON (sorted keys) for digests of definitions and approval actions.
+    def canonical_json(value)
+      case value
+      when Hash then "{" + value.map { |k, v| [ k.to_s, v ] }.sort_by(&:first).map { |k, v| "#{k.to_json}:#{canonical_json(v)}" }.join(",") + "}"
+      when Array then "[" + value.map { |v| canonical_json(v) }.join(",") + "]"
+      when Symbol then value.to_s.to_json
+      else value.to_json
+      end
+    end
+
+    def canonical_digest(value) = digest(canonical_json(value))
+  end
+end
+require "openssl"

data/lib/agentboard/json_log_formatter.rb

@@ -0,0 +1,28 @@
+require "logger"
+
+module Agentboard
+  # Structured log records (spec §32.1): timestamp, level, component, correlation and
+  # execution ids, event name. Messages are redacted; payloads are never logged.
+  class JsonLogFormatter < ::Logger::Formatter
+    def initialize(component: "runtime")
+      super()
+      @component = component
+    end
+
+    def call(severity, time, _progname, msg)
+      record = { ts: time.utc.iso8601(3), level: severity.downcase, component: @component, pid: ::Process.pid }
+      if defined?(Agentboard::Current)
+        record[:correlation_id] = Agentboard::Current.correlation_id if Agentboard::Current.correlation_id
+      end
+      record[:thread] = Thread.current.name if Thread.current.name
+      text = msg.is_a?(Exception) ? "#{msg.class}: #{msg.message}" : msg.to_s
+      if (m = text.match(/\A\[agentboard(?:\.(\w+))?\]\s*/))
+        record[:component] = m[1] if m[1]
+        text = m.post_match
+      end
+      record[:execution_id] = text[/\b([0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12})\b/, 1] if text.include?("execution")
+      record[:message] = Redactor.redact(text)[0, 4000]
+      JSON.generate(record.compact) + "\n"
+    end
+  end
+end

data/lib/agentboard/path_guard.rb

@@ -0,0 +1,27 @@
+module Agentboard
+  # Canonicalizes paths and rejects traversal or symlink escape outside an allowed root
+  # (spec §29.2, §30.2). Used for every AgentBoard-managed file operation.
+  module PathGuard
+    module_function
+
+    def within!(root, path)
+      root_real = File.realpath(root.to_s)
+      candidate = File.expand_path(path.to_s, root_real)
+      # Resolve the deepest existing ancestor so symlinks anywhere in the chain are followed.
+      probe = candidate
+      probe = File.dirname(probe) until File.exist?(probe) || probe == "/"
+      resolved = File.join(File.realpath(probe), candidate.delete_prefix(probe))
+      resolved = File.expand_path(resolved)
+      unless resolved == root_real || resolved.start_with?(root_real + File::SEPARATOR)
+        raise Error.validation_failed("Path escapes the allowed workspace", path: path.to_s)
+      end
+
+      resolved
+    end
+
+    def safe_relative?(path)
+      p = path.to_s
+      !p.empty? && !p.start_with?("/") && !p.split(%r{[/\\]}).include?("..") && !p.include?("\0")
+    end
+  end
+end

data/lib/agentboard/process_ancestry.rb

@@ -0,0 +1,40 @@
+module Agentboard
+  # Finds the agent process (claude, codex, cursor-agent…) that spawned the current process.
+  # MCP servers and hook commands are both children of the same agent process, which lets
+  # AgentBoard correlate an MCP session with the provider's hook-reported session without
+  # trusting any identifier supplied by the agent. Works on macOS and Linux (`ps`).
+  module ProcessAncestry
+    AGENT_COMMANDS = /\A(claude|codex|cursor-agent|cursor|gemini|opencode|copilot)\z/i
+    MAX_DEPTH = 12
+
+    Agent = Struct.new(:pid, :command, :fingerprint, keyword_init: true) do
+      def to_h = { "agent_pid" => pid, "agent_command" => command, "agent_fingerprint" => fingerprint }
+    end
+
+    module_function
+
+    def find_agent(start_pid = ::Process.ppid)
+      pid = start_pid
+      MAX_DEPTH.times do
+        break if pid.nil? || pid <= 1
+
+        ppid, comm = info(pid)
+        name = File.basename(comm.to_s)
+        return Agent.new(pid: pid, command: name, fingerprint: Subprocess.fingerprint(pid)) if name.match?(AGENT_COMMANDS)
+
+        pid = ppid
+      end
+      nil
+    end
+
+    def info(pid)
+      out, _e, st = Open3.capture3("ps", "-o", "ppid=,comm=", "-p", pid.to_s)
+      return [ nil, nil ] unless st.success?
+
+      ppid, comm = out.strip.split(/\s+/, 2)
+      [ ppid.to_i, comm ]
+    rescue StandardError
+      [ nil, nil ]
+    end
+  end
+end

data/lib/agentboard/providers/base.rb

@@ -0,0 +1,107 @@
+module Agentboard
+  module Providers
+    # Provider adapter contract. Passive (MCP/hooks/event ingestion) and active
+    # (launch/stream/cancel/resume) are separate concerns so partial support is explicit.
+    # Unsupported features raise UnsupportedCapability (CAPABILITY_UNAVAILABLE).
+    class Base
+      class << self
+        def key = raise(NotImplementedError)
+        def display_name = key.to_s.capitalize
+        def binary = nil
+
+        # Compatibility manifest: lib/agentboard/providers/compatibility/<key>.yml
+        def compatibility
+          @compatibility ||= begin
+            path = File.expand_path("compatibility/#{key}.yml", __dir__)
+            File.exist?(path) ? YAML.safe_load(File.read(path), aliases: false) : { "provider" => key.to_s, "validated" => [] }
+          end
+        end
+      end
+
+      attr_reader :settings
+
+      def initialize(settings: nil)
+        @settings = settings || Agentboard.config.provider_settings(self.class.key)
+      end
+
+      def key = self.class.key.to_s
+      def display_name = self.class.display_name
+
+      # -- discovery -----------------------------------------------------------------
+      def probe(environment: ENV) = raise(NotImplementedError)
+      def capabilities(environment: ENV) = probe(environment: environment).supported_capabilities
+      def detect = probe.installed
+      def supports?(cap) = Array(capabilities).include?(cap.to_sym)
+
+      # -- passive -------------------------------------------------------------------
+      def install_passive_hooks(project:, root:) = raise(UnsupportedCapability.new(:passive_hooks, provider: key))
+      def remove_passive_hooks(project:, root:, manifest:) = raise(UnsupportedCapability.new(:passive_hooks, provider: key))
+      def configure_passive(context:) = install_passive_hooks(project: context[:project], root: context[:root])
+
+      # Maps a raw hook payload to [NormalizedEvent] (hook ingestion).
+      def parse_hook(event_name:, payload:) = raise(UnsupportedCapability.new(:passive_hooks, provider: key))
+
+      # -- active --------------------------------------------------------------------
+      def launch_spec(execution:, worktree:, context_path:, prompt:) = raise(UnsupportedCapability.new(:active_execution, provider: key))
+
+      # Parses one line of provider stdout into zero or more NormalizedEvents.
+      def parse_event(raw_event:) = raise(UnsupportedCapability.new(:structured_events, provider: key))
+
+      def resume_spec(execution:, worktree:, input:) = raise(UnsupportedCapability.new(:session_resume, provider: key))
+
+      # Cancellation is performed by the supervisor via the process group; providers that
+      # need protocol-level interruption override this.
+      def interrupt(handle:)
+        raise UnsupportedCapability.new(:cancellation, provider: key) unless supports?(:cancellation)
+
+        Subprocess.terminate(handle.fetch(:pgid), grace: Agentboard.config.runtime["cancel_grace_seconds"].to_i)
+      end
+
+      # Back-compat names from spec §5.
+      def start(execution:) = raise(UnsupportedCapability.new(:active_execution, provider: key))
+      def events(session:, cursor: nil) = raise(UnsupportedCapability.new(:structured_events, provider: key))
+      def cancel(session:) = raise(UnsupportedCapability.new(:cancellation, provider: key))
+      def resume(handle:, input: nil) = raise(UnsupportedCapability.new(:session_resume, provider: key))
+
+      protected
+
+      def run_version(argv)
+        out, _err, status = Open3.capture3(Subprocess.scrubbed_env, *argv)
+        status.success? ? out.strip : nil
+      rescue Errno::ENOENT, Errno::EACCES
+        nil
+      end
+
+      def which(bin)
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |dir|
+          path = File.join(dir, bin)
+          return path if File.file?(path) && File.executable?(path)
+        end
+        nil
+      end
+
+      # Conservative capability negotiation (AT-14): capabilities listed for a validated
+      # version are enabled; unknown versions only get passive, low-risk capabilities unless
+      # the operator explicitly opts in with `allow_unvalidated_versions: true`.
+      def negotiate(version, all_caps, safe_caps: %i[mcp])
+        entry = Array(self.class.compatibility["validated"]).find { |v| version.to_s.include?(v["binary_version"].to_s) }
+        if entry
+          caps = Array(entry["capabilities"]).map(&:to_sym) & all_caps
+          [ caps, entry["status"] || "validated", [ entry["smoke_test"] ].compact ]
+        elsif settings["allow_unvalidated_versions"]
+          [ all_caps, "unvalidated (operator opt-in)", [ "#{display_name} #{version} is not in the compatibility manifest; running with operator opt-in." ] ]
+        else
+          [ safe_caps & all_caps, "unknown version",
+            [ "#{display_name} #{version || "(unknown)"} is not in the compatibility manifest. Active execution is disabled; " \
+              "set providers.#{key}.allow_unvalidated_versions: true to opt in after testing." ] ]
+        end
+      end
+
+      def safe_json(line)
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end