gitbroker 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 31100d13953d9e191985df3879c813d7c099bc1b63bb4131e1525c14678f6a0e
+  data.tar.gz: 62d14854178753254f2625997bd99e30239f4f040a2a6c77a74fa42eed3a8f8d
+SHA512:
+  metadata.gz: 8660d0d75f555a54866a226a4b082e007036901151ba2af069e4eadb6d8c30e5ede3826d3dc815ed749f18c950dfdc68055a23b60d80841828515eb3f2663491
+  data.tar.gz: 5e52cc5c07ad6400dd8e9eac3bb9ceef06ea1dd0a353b693e006f3865fb0f4c685776c41144ddba9b2e2a369d525f0c6ba6e3ce31fb06261dd843181559d0fee

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GitBroker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/exe/gitbroker

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/gitbroker"
+
+begin
+  exit Gitbroker::CLI.new(ARGV).run
+rescue Interrupt
+  exit 130
+end

data/lib/gitbroker/agents/base.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Gitbroker
+  module Agents
+    class Base
+      TOKEN_ENV = "GITBROKER_TASK_TOKEN"
+      MAX_PATH = 100
+
+      def initialize(config:, worktree:)
+        @config = config
+        @worktree = worktree.to_s.chomp("/")
+      end
+
+      # The run's lines for the user's log: what the model said and the tools it called. Subclasses override.
+      def parse_log(_line) = []
+
+      def env(token, task_id) = { TOKEN_ENV => token, "GITBROKER_TASK_ID" => task_id }
+
+      private
+
+      # Spec §5.2: progress carries tool names and paths inside the worktree only.
+      def step(verb, path = nil, noun: "a file")
+        path = path.is_a?(String) ? path : ""
+        relative = path.start_with?("#{@worktree}/") ? path.delete_prefix("#{@worktree}/") : nil
+        return "#{verb} #{noun}" if relative.nil? || relative.empty? || relative.include?("..") || relative.match?(/[[:cntrl:]]/)
+
+        "#{verb} #{relative[0, MAX_PATH]}"
+      end
+
+      def parse_json(line)
+        event = JSON.parse(line)
+        event.is_a?(Hash) ? event : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      # The URL is written into a TOML override (Codex), so it must be a plain http(s) URL.
+      def mcp_url(mcp_config)
+        url = JSON.parse(File.read(mcp_config)).dig("mcpServers", "gitbroker", "url").to_s
+        raise Error, "Invalid GitBroker MCP URL #{url.inspect} in #{mcp_config}" unless url.match?(%r{\Ahttps?://[^\s"'\\]+\z})
+
+        url
+      end
+    end
+  end
+end

data/lib/gitbroker/agents/claude.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Gitbroker
+  module Agents
+    # Claude Code. Autonomous: `claude -p … --output-format stream-json --verbose` (spec §4.2 step 5); the programmatic
+    # credit pool pays for it (spec §2). Terminal: interactive `claude`.
+    class Claude < Base
+      PLUGIN_DIR = File.join(Gitbroker::ROOT, "plugin")
+      READ_ONLY_ARGS = [ "--permission-mode", "dontAsk", "--permission-prompts", "none",
+                         "--allowedTools", "Read,Grep,Glob,mcp__gitbroker__*",
+                         "--disallowedTools", "Bash,Edit,Write,NotebookEdit,WebFetch,WebSearch" ].freeze
+      READS = %w[Read NotebookRead].freeze
+      EDITS = %w[Edit MultiEdit Write NotebookEdit].freeze
+
+      def initialize(config:, worktree:, plugin_dir: PLUGIN_DIR)
+        super(config:, worktree:)
+        @plugin_dir = plugin_dir
+      end
+
+      def name = "claude_code"
+
+      def autonomous_command(task, mcp_config:)
+        args = task["read_only"] ? READ_ONLY_ARGS : @config.claude_args
+        [ @config.claude_command, "-p", task.fetch("prompt"), "--output-format", "stream-json", "--verbose", *args,
+          "--mcp-config", mcp_config, *strict(task), "--plugin-dir", @plugin_dir ]
+      end
+
+      def terminal_command(task, mcp_config:)
+        [ @config.claude_command, "--mcp-config", mcp_config, *strict(task), "--plugin-dir", @plugin_dir ]
+      end
+
+      def parse_stream(line)
+        event = parse_json(line) or return nil
+
+        case event["type"]
+        when "system" then Progress.new(step: "starting", session_id: event["session_id"]) if event["subtype"] == "init"
+        when "assistant"
+          tool = Array(event.dig("message", "content")).reverse.find { _1.is_a?(Hash) && _1["type"] == "tool_use" }
+          tool && Progress.new(step: step_for(tool["name"].to_s, tool["input"].is_a?(Hash) ? tool["input"] : {}), session_id: nil)
+        when "result"
+          Result.new(cost_usd: event["total_cost_usd"], text: event["result"].to_s, error: event["is_error"] == true)
+        end
+      end
+
+      # Assistant text and thinking, each tool call (a name and a path or a short command), and the final answer. A tool's
+      # result is the file contents it read, which stay on the machine (spec §5.2).
+      def parse_log(line)
+        event = parse_json(line) or return []
+
+        case event["type"]
+        when "assistant" then Array(event.dig("message", "content")).filter_map { log_block(_1) }
+        when "result" then event["result"].to_s.strip.empty? ? [] : [ Entry.new(kind: event["is_error"] == true ? "error" : "result", text: event["result"].to_s) ]
+        else []
+        end
+      end
+
+      private
+
+      def log_block(block)
+        return unless block.is_a?(Hash)
+
+        case block["type"]
+        when "text" then Entry.new(kind: "text", text: block["text"].to_s) unless block["text"].to_s.strip.empty?
+        when "thinking" then Entry.new(kind: "thinking", text: block["thinking"].to_s) unless block["thinking"].to_s.strip.empty?
+        when "tool_use" then Entry.new(kind: "tool", text: tool_line(block["name"].to_s, block["input"].is_a?(Hash) ? block["input"] : {}))
+        end
+      end
+
+      def tool_line(tool, input)
+        detail = input["file_path"] || input["notebook_path"] || input["pattern"] || input["command"] || input["path"]
+        detail = relative_path(detail) if detail.is_a?(String)
+        [ tool.gsub(/[^\w-]/, "")[0, 40], (detail.to_s.gsub(/[[:cntrl:]]/, " ")[0, 200] if detail.is_a?(String)) ].compact.join(" ")
+      end
+
+      def relative_path(value) = value.start_with?("#{@worktree}/") ? value.delete_prefix("#{@worktree}/") : value
+
+      def strict(task) = task["untrusted"] ? [ "--strict-mcp-config" ] : []
+
+      def step_for(tool, input)
+        case tool
+        when *READS then step("reading", input["file_path"])
+        when *EDITS then step("editing", input["file_path"] || input["notebook_path"])
+        when "Bash" then "running a command"
+        when "Grep", "Glob" then "searching"
+        when /\Amcp__gitbroker__(\w+)\z/ then "calling #{Regexp.last_match(1)}"
+        when "TodoWrite" then "planning"
+        else "using #{tool.gsub(/[^\w-]/, "")[0, 40]}"
+        end
+      end
+    end
+  end
+end

data/lib/gitbroker/agents/codex.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Gitbroker
+  module Agents
+    # Codex. Autonomous: `codex exec --json` in a workspace-write sandbox with network (spec §4.2 step 5); the MCP
+    # server is configured for this run only with -c overrides. Codex reports no cost (counted as unknown).
+    # Read-only kinds use `--sandbox read-only`: Codex still runs shell commands there (read-only filesystem, no network),
+    # so it is not a no-exec mode. It also loads the user's own MCP servers (no --strict-mcp-config), which is why
+    # TaskRunner never runs Codex headless on an untrusted head.
+    class Codex < Base
+      READ_ONLY_ARGS = %w[--sandbox read-only].freeze
+
+      def name = "codex"
+
+      def autonomous_command(task, mcp_config:)
+        args = task["read_only"] ? READ_ONLY_ARGS : @config.codex_args
+        [ @config.codex_command, "exec", "--json", *args, *mcp_overrides(mcp_config), task.fetch("prompt") ]
+      end
+
+      def terminal_command(_task, mcp_config:) = [ @config.codex_command, *mcp_overrides(mcp_config) ]
+
+      def parse_stream(line)
+        event = parse_json(line) or return nil
+
+        case event["type"]
+        when "thread.started" then Progress.new(step: "starting", session_id: event["thread_id"])
+        when "item.started", "item.completed" then item(event["item"].is_a?(Hash) ? event["item"] : {})
+        when "turn.completed" then Result.new(cost_usd: nil, text: @last_message.to_s, error: false)
+        when "turn.failed", "error" then Result.new(cost_usd: nil, text: @last_message.to_s, error: true)
+        end
+      end
+
+      def parse_log(line)
+        event = parse_json(line) or return []
+        return [] unless %w[item.completed].include?(event["type"]) && event["item"].is_a?(Hash)
+
+        item = event["item"]
+        case item["type"]
+        when "agent_message" then item["text"].to_s.strip.empty? ? [] : [ Entry.new(kind: "text", text: item["text"].to_s) ]
+        when "reasoning" then item["text"].to_s.strip.empty? ? [] : [ Entry.new(kind: "thinking", text: item["text"].to_s) ]
+        when "command_execution" then [ Entry.new(kind: "tool", text: "Ran #{item["command"].to_s.gsub(/[[:cntrl:]]/, " ")[0, 200]}") ]
+        when "file_change" then [ Entry.new(kind: "tool", text: step("edited", first_change_path(item["changes"]))) ]
+        when "mcp_tool_call" then [ Entry.new(kind: "tool", text: "Called #{item["tool"].to_s.gsub(/[^\w]/, "")[0, 40]}") ]
+        else []
+        end
+      end
+
+      private
+
+      def item(item)
+        case item["type"]
+        when "command_execution" then Progress.new(step: "running a command", session_id: nil)
+        when "file_change" then Progress.new(step: step("editing", first_change_path(item["changes"])), session_id: nil)
+        when "mcp_tool_call" then Progress.new(step: "calling #{item["tool"].to_s.gsub(/[^\w]/, "")[0, 40]}", session_id: nil)
+        when "agent_message"
+          @last_message = item["text"]
+          nil
+        end
+      end
+
+      def first_change_path(changes)
+        change = changes.is_a?(Array) ? changes.first : nil
+        change.is_a?(Hash) ? change["path"] : nil
+      end
+
+      def mcp_overrides(mcp_config)
+        [ "-c", %(mcp_servers.gitbroker.url="#{mcp_url(mcp_config)}"),
+          "-c", %(mcp_servers.gitbroker.env_http_headers={ "x-task-token" = "#{TOKEN_ENV}" }) ]
+      end
+    end
+  end
+end

data/lib/gitbroker/agents.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Gitbroker
+  # The user's own coding agents, run headless (autonomous) or interactively (terminal). Spec §4.2 steps 5–7.
+  module Agents
+    Progress = Data.define(:step, :session_id)
+    Result = Data.define(:cost_usd, :text, :error)
+    # One line of the run for the user's own log (kind: text, thinking, tool, error or result). Tool results (file
+    # contents) are never an entry.
+    Entry = Data.define(:kind, :text)
+
+    autoload :Base, File.expand_path("agents/base", __dir__)
+    autoload :Claude, File.expand_path("agents/claude", __dir__)
+    autoload :Codex, File.expand_path("agents/codex", __dir__)
+
+    def self.for(config, worktree:) = (config.agent == "codex" ? Codex : Claude).new(config:, worktree:)
+  end
+end

data/lib/gitbroker/api.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Gitbroker
+  # JSON POST client for GitBroker's companion endpoints (bearer device or task token).
+  class Api
+    class HttpError < Error
+      attr_reader :status, :body
+
+      def initialize(status, body)
+        @status = status
+        @body = body.is_a?(Hash) ? body : {}
+        super("HTTP #{status}: #{@body["error"] || body}")
+      end
+    end
+
+    def initialize(server:, token: nil)
+      @server = server.to_s.chomp("/")
+      @token = token
+    end
+
+    def post(path, body = {})
+      uri = URI("#{@server}#{path}")
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json"
+      request["User-Agent"] = "gitbroker/#{VERSION}"
+      request["Authorization"] = "Bearer #{@token}" if @token
+      request.body = JSON.generate(body)
+
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 10, read_timeout: 30) do |http|
+        http.request(request)
+      end
+      parsed = parse(response.body)
+      raise HttpError.new(response.code.to_i, parsed) unless response.is_a?(Net::HTTPSuccess)
+
+      parsed
+    end
+
+    private
+
+    def parse(body)
+      return {} if body.to_s.strip.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      { "error" => body.to_s[0, 200] }
+    end
+  end
+end

data/lib/gitbroker/cable_client.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "openssl"
+require "uri"
+require "websocket/driver"
+
+module Gitbroker
+  # One outbound WebSocket to GitBroker's Action Cable (spec §4.1: no listening ports), one thread: IO.select drives
+  # reads, writes, ticks, polls and staleness. `perform` may be called from any thread (task runners report from their
+  # own); it only queues the frame and wakes the loop, so the socket (an SSL socket in production, which is not safe
+  # for concurrent reads and writes) is only ever touched by the thread in `run`. One client serves one connection.
+  class CableClient
+    class Unauthorized < Error; end
+    class HandshakeError < Error; end
+
+    # Action Cable's JSON wire format for DeviceChannel.
+    class Protocol
+      CHANNEL = "DeviceChannel"
+
+      def identifier = JSON.generate({ channel: CHANNEL })
+      def subscribe = JSON.generate({ command: "subscribe", identifier: })
+
+      def perform(action, data = {})
+        JSON.generate({ command: "message", identifier:, data: JSON.generate(data.merge("action" => action)) })
+      end
+
+      def parse(raw)
+        message = JSON.parse(raw)
+        return [ :ignored ] unless message.is_a?(Hash)
+
+        case message["type"]
+        when "welcome" then [ :welcome ]
+        when "ping" then [ :ping ]
+        when "confirm_subscription" then [ :confirmed ]
+        when "reject_subscription" then [ :rejected ]
+        when "disconnect" then [ :disconnect, message["reason"], message["reconnect"] ]
+        else message["identifier"] == identifier && message["message"].is_a?(Hash) ? [ :message, message["message"] ] : [ :ignored ]
+        end
+      rescue JSON::ParserError
+        [ :ignored ]
+      end
+    end
+
+    SUBPROTOCOL = "actioncable-v1-json"
+    STALE_AFTER = 20
+    TICK_EVERY = 30
+    POLL_EVERY = 1
+    SELECT_TIMEOUT = 1
+    CONNECT_TIMEOUT = 10
+    READ_CHUNK = 16_384
+
+    SocketAdapter = Struct.new(:url, :io) do
+      def write(data) = io.write(data)
+    end
+
+    def initialize(url:, token:, origin:, protocol: Protocol.new)
+      @url = url
+      @token = token
+      @origin = origin
+      @protocol = protocol
+      @outbox = Queue.new
+      @wake_reader, @wake_writer = IO.pipe
+    end
+
+    def on_subscribed(&block) = @on_subscribed = block
+    def on_message(&block) = @on_message = block
+    def on_tick(&block) = @on_tick = block
+    def on_poll(&block) = @on_poll = block
+
+    def perform(action, data = {})
+      @outbox << @protocol.perform(action, data)
+      wake
+    end
+
+    def stop
+      @stopped = true
+      wake
+    end
+
+    def run
+      @stopped = false
+      @welcomed = false
+      @subscribed = false
+      @io = open_socket
+      @driver = build_driver
+      @driver.start
+      @started = @last_ping = @last_tick = monotonic
+      @last_poll = 0.0
+      pump
+      final_flush
+    ensure
+      @io.close if @io && !@io.closed?
+      [ @wake_reader, @wake_writer ].each(&:close)
+    end
+
+    private
+
+    def build_driver
+      driver = WebSocket::Driver.client(SocketAdapter.new(@url, @io), protocols: [ SUBPROTOCOL ])
+      driver.set_header("Authorization", "Bearer #{@token}")
+      driver.set_header("Origin", @origin)
+      driver.on(:message) { |event| dispatch(event.data) }
+      driver.on(:close) { @stopped = true }
+      driver.on(:error) { |event| raise HandshakeError, event.message unless @welcomed }
+      driver
+    end
+
+    def pump
+      until @stopped
+        break if read == :eof
+
+        flush
+        stale!
+        tick
+        poll
+      end
+    end
+
+    def read
+      readable = @io.respond_to?(:pending) && @io.pending.positive? ? [ @io ] : IO.select([ @io, @wake_reader ], nil, nil, SELECT_TIMEOUT)&.first
+      return unless readable
+
+      @wake_reader.read_nonblock(1024, exception: false) if readable.include?(@wake_reader)
+      return unless readable.include?(@io)
+
+      chunk = @io.read_nonblock(READ_CHUNK, exception: false)
+      return :eof if chunk.nil?
+
+      @driver.parse(chunk) if chunk.is_a?(String)
+    end
+
+    def flush
+      return unless @welcomed
+
+      @driver.text(@outbox.pop) until @outbox.empty?
+    end
+
+    # Reports queued just before a stop (a task's `finished`) still go out; a dead socket just drops them.
+    def final_flush
+      flush
+    rescue IOError, SystemCallError, OpenSSL::SSL::SSLError
+      nil
+    end
+
+    def stale!
+      if @welcomed
+        @stopped = true if monotonic - @last_ping > STALE_AFTER
+      elsif monotonic - @started > STALE_AFTER
+        raise HandshakeError, "No welcome from #{@url} within #{STALE_AFTER} s"
+      end
+    end
+
+    def tick
+      return if monotonic - @last_tick < TICK_EVERY
+
+      @last_tick = monotonic
+      @on_tick&.call
+    end
+
+    def poll
+      return unless @subscribed && monotonic - @last_poll >= POLL_EVERY
+
+      @last_poll = monotonic
+      @on_poll&.call
+    end
+
+    def dispatch(raw)
+      kind, *rest = @protocol.parse(raw)
+      case kind
+      when :welcome
+        @welcomed = true
+        @last_ping = monotonic
+        @driver.text(@protocol.subscribe)
+      when :ping then @last_ping = monotonic
+      when :confirmed
+        @subscribed = true
+        @on_subscribed&.call
+      when :rejected then raise Unauthorized, "The server rejected the device channel subscription"
+      when :disconnect
+        raise Unauthorized, "The server rejected this device token" if rest.first == "unauthorized"
+
+        @stopped = true
+      when :message then @on_message&.call(rest.first)
+      end
+    end
+
+    def wake
+      @wake_writer.write_nonblock(".", exception: false)
+    rescue IOError
+      nil
+    end
+
+    def open_socket
+      uri = URI(@url)
+      raise Error, "Invalid cable URL #{@url.inspect}" unless %w[ws wss].include?(uri.scheme) && uri.host
+
+      tcp = Socket.tcp(uri.host, uri.port, connect_timeout: CONNECT_TIMEOUT)
+      return tcp unless uri.scheme == "wss"
+
+      context = OpenSSL::SSL::SSLContext.new
+      context.set_params(verify_mode: OpenSSL::SSL::VERIFY_PEER, verify_hostname: true)
+      ssl = OpenSSL::SSL::SSLSocket.new(tcp, context)
+      ssl.hostname = uri.host
+      ssl.sync_close = true
+      ssl.connect
+      ssl
+    end
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end