ruby_llm-providers-copilot 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ca732cce7361f198dca083229e205cd488da6e9dc39e8f37c85db61e714b86b2
+  data.tar.gz: db1ca71d41292caa7d029ab0441215e6c9f9a844986d0114bbcda160f5205e3e
+SHA512:
+  metadata.gz: b1aa9714488725e3ea95fd671e4cd89f7f20102c03c2d3299f25969143d5f6702ac131aeee9b27b9ee674a5de8e5982bbfcf716f3c2ffb09fe70716de95cee9f
+  data.tar.gz: cfca36186324fb9eddd04335406433689805c3b74c9ddf32e2a19d1ad2a15921eaaaa54020852606cf8a30264ab9da67e2b2130ba70551a0e8a3f2a12f7ea9f1

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-11-06
+
+- Initial release: the GitHub Copilot CLI as a RubyLLM provider with resumable
+  sessions, streaming, reasoning effort and attachment notes.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dewayne VanHoozer
+
+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/README.md

@@ -0,0 +1,103 @@
+# ruby_llm-providers-copilot
+
+A [RubyLLM](https://rubyllm.com) provider that uses the **GitHub Copilot CLI
+agent** as the model. Each completion runs `copilot` in non-interactive mode,
+pipes the prompt on stdin and reads the JSON event stream from stdout.
+
+This is deliberately *not* an isolated stand-in for a model API. The agent
+keeps its own tools, MCP servers and instructions, and it works in the
+current directory. Multi-turn chats resume the same Copilot session, so the
+agent keeps its context between turns.
+
+```ruby
+require 'ruby_llm/providers/copilot'
+
+chat = RubyLLM.chat(model: 'default', provider: :copilot)
+chat.ask('What does the Rakefile in this directory do?')
+chat.ask('Add a `lint` task to it') { |chunk| print chunk.content }
+```
+
+With [aia](https://github.com/madbomber/aia) the provider is picked from the
+model prefix:
+
+```bash
+aia --model copilot/default review_prompt
+aia --model claude_code/sonnet=implementer,copilot/auto=reviewer --consensus review
+```
+
+## Requirements
+
+- Ruby 3.2 or newer
+- RubyLLM 2.1 or newer
+- The GitHub Copilot CLI on your PATH (`copilot --version`), logged in with
+  `copilot login`. No API key is read by this gem.
+
+## Installation
+
+```ruby
+gem 'ruby_llm-providers-copilot', require: 'ruby_llm/providers/copilot'
+```
+
+The provider registers itself as `:copilot` when required.
+
+## Models
+
+The part after the slash goes straight to `copilot --model`. The id `default`
+(or an empty id) sends no `--model` flag; `auto` lets Copilot route.
+
+## Sessions
+
+Copilot lets the caller choose the session id, so every new session gets a
+UUID from this gem (`--session-id`). When the transcript minus the newest
+message matches what that session already saw, only the new message is sent
+with `--resume <id>`. Any other shape (rewound or edited history, a cleared
+chat, a changed system prompt) starts a fresh session with the conversation
+replayed as a tagged transcript.
+
+```ruby
+chat.with_provider_options(copilot: { resume: false })      # fresh session every turn
+chat.with_provider_options(copilot: { session_id: 'uuid' }) # continue a known session
+```
+
+## Configuration
+
+Global options are `RubyLLM.config.copilot_*`; the same keys can be set per
+chat with `with_provider_options(copilot: { ... })`.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `command` | `copilot` | CLI executable |
+| `cwd` | current directory | Directory the agent works in |
+| `timeout` | `600` | Seconds before the process group is killed; `nil` or `0` disables |
+| `allow_all_tools` | `false` | Pass `--allow-all-tools` so the agent runs tools without confirmation |
+| `args` | none | Extra CLI arguments, array or shell string (`--add-dir`, `--allow-tool`, `--agent`, ...) |
+| `env` | none | Extra environment variables for the process |
+| `resume` | `true` | Reuse the session across turns |
+| `session_id` | none | Per-request only: resume this session id |
+
+## What is supported
+
+| Feature | How |
+|---|---|
+| Text, system prompts, multi-turn | Copilot has no system-prompt flag, so instructions lead the first prompt in an `<instructions>` block; see Sessions |
+| Streaming | `assistant.message_delta` events become chunks |
+| `with_thinking(effort:)` | `--reasoning-effort` (none, minimal, low, medium, high, xhigh, max) |
+| Token counts | Summed from the session usage checkpoint: input, output, cache read and write |
+| Attachments | Noted in the prompt as `[Attached file 'name': path]`; the agent opens local files itself |
+| RubyLLM tools (`with_tools`) | **Not supported**: raises `UnsupportedFeatureError`. The provider class answers `accepts_tools?` with `false` so hosts such as aia can skip attaching tools |
+| Structured output (`with_schema`) | **Not supported**: the CLI has no schema option |
+| temperature, max tokens | Ignored (logged at debug level) |
+
+## Safety
+
+Without `allow_all_tools` the CLI applies its own confirmation rules, and in
+non-interactive mode an unapproved tool simply is not run. Turn it on only in
+a directory you are happy to let the agent change.
+
+## Development
+
+```bash
+bundle install
+asgard test_verbose       # offline: the CLI is replaced by a fake runner
+asgard quality            # tests, rubocop, flog, flay, reek, ...
+```

data/lib/ruby_llm/providers/copilot/command.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Copilot < Provider
+      # Builds the argv for one non-interactive `copilot` run. The prompt is
+      # piped on stdin; copilot has no system-prompt flag, so instructions are
+      # folded into the prompt by the provider.
+      class Command
+        EFFORTS = %w[none minimal low medium high xhigh max].freeze
+
+        def initialize(settings)
+          @settings = settings
+        end
+
+        # @param model [String, nil] model id; "default" means the CLI's own choice
+        # @param session_id [String] id for a new session (copilot lets the caller pick it)
+        # @param resume_id [String, nil] session id to continue instead
+        # @param effort [String, nil] one of EFFORTS
+        # @return [Array<String>]
+        def build(session_id:, model: nil, resume_id: nil, effort: nil)
+          argv = [@settings.command, '--silent', '--output-format', 'json']
+          argv.push('--model', model.to_s) if self.class.named?(model)
+          argv.push(*(resume_id ? ['--resume', resume_id] : ['--session-id', session_id]))
+          argv.push('--reasoning-effort', effort) if effort
+          argv << '--allow-all-tools' if @settings.allow_all_tools?
+          argv.concat(@settings.args)
+        end
+
+        class << self
+          def named?(model)
+            !(model.nil? || model.to_s.empty? || model.to_s == DEFAULT_MODEL)
+          end
+
+          # Instructions have no flag of their own, so they lead the prompt
+          # of a new session.
+          def prompt_with_instructions(prompt, system_prompt)
+            return prompt if system_prompt.nil? || system_prompt.strip.empty?
+
+            "<instructions>\n#{system_prompt}\n</instructions>\n\n#{prompt}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/copilot/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Copilot < Provider
+      # Raised when the copilot CLI cannot be run, exits without a result, or
+      # reports an error of its own.
+      class Error < RubyLLM::Error; end
+
+      # Raised when the CLI runs past the configured timeout and is killed.
+      class TimeoutError < Error; end
+
+      # Raised for RubyLLM features the CLI cannot honour, such as tools.
+      class UnsupportedFeatureError < Error; end
+    end
+  end
+end

data/lib/ruby_llm/providers/copilot/response.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RubyLLM
+  module Providers
+    class Copilot < Provider
+      # Reads `copilot --output-format json` events line by line. Message
+      # deltas are streamed as Chunks, the last assistant.message is the
+      # reply, and session.usage_checkpoint carries the token usage.
+      class Response
+        USAGE_KEYS = {
+          'inputTokens' => :input, 'outputTokens' => :output,
+          'cacheReadTokens' => :cache_read, 'cacheWriteTokens' => :cache_write, 'reasoningTokens' => :thinking
+        }.freeze
+
+        attr_reader :session_id, :model_id
+
+        def initialize(model:, session_id:)
+          @model      = model
+          @session_id = session_id
+          @content    = nil
+          @usage      = nil
+          @error      = nil
+        end
+
+        # @param line [String] one line of stdout
+        # @yield [RubyLLM::Chunk] a streamed piece of assistant text
+        # @return [Hash, nil] the parsed event, or nil for non-JSON lines
+        def ingest(line)
+          event = self.class.parse(line)
+          return nil unless event
+
+          data = event['data'] || {}
+          case event['type']
+          when 'assistant.message_delta'
+            text = data['deltaContent']
+            yield chunk(text) if text && !text.empty? && block_given?
+          when 'assistant.message'
+            @content  = data['content'].to_s
+            @model_id = data['model']
+          when 'session.usage_checkpoint' then @usage = self.class.usage_from(data)
+          when 'error', 'session.error', 'assistant.error' then @error = (data['message'] || data['error'] || data).to_s
+          end
+          event
+        end
+
+        # @param run [Runner::Result, nil] used for diagnostics when no reply arrived
+        # @return [RubyLLM::Message]
+        def message(run = nil)
+          raise Error, "copilot failed: #{@error}" if @error
+
+          raise_without_result!(run) if @content.nil?
+
+          Message.new(
+            role: :assistant,
+            content: @content,
+            model: @model,
+            tokens: Tokens.new(**(@usage || {})),
+            finish_reason: :stop,
+            raw: { 'session_id' => @session_id, 'model' => @model_id, 'usage' => @usage }
+          )
+        end
+
+        class << self
+          def parse(line)
+            text = line.to_s.strip
+            return nil unless text.start_with?('{')
+
+            JSON.parse(text)
+          rescue JSON::ParserError
+            RubyLLM.logger.debug { "copilot: non-JSON output #{text.inspect}" }
+            nil
+          end
+
+          # Sums the per-model usage in a usage checkpoint into Tokens kwargs.
+          def usage_from(data)
+            metrics = data.dig('accountingSnapshot', 'modelMetrics') || {}
+            totals = Hash.new(0)
+            metrics.each_value do |entry|
+              (entry['usage'] || {}).each do |key, value|
+                field = USAGE_KEYS[key]
+                totals[field] += value.to_i if field
+              end
+            end
+            totals.empty? ? nil : totals
+          end
+        end
+
+        private
+
+        def raise_without_result!(run)
+          status = run&.status&.exitstatus
+          stderr = run&.stderr.to_s.strip
+          raise Error,
+                "copilot exited#{" (#{status})" if status} without a reply#{": #{stderr}" unless stderr.empty?}"
+        end
+
+        def chunk(text)
+          Chunk.new(role: :assistant, content: text, model: @model)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/copilot/runner.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module RubyLLM
+  module Providers
+    class Copilot < Provider
+      # Spawns the CLI, feeds it stdin, and yields each stdout line on the
+      # caller's thread as it arrives. The process group is killed when the
+      # timeout passes.
+      class Runner
+        # What the process produced: full stdout, full stderr, and its exit status.
+        Result = Data.define(:stdout, :stderr, :status)
+        GRACE_SECONDS = 2
+        EOF = Object.new.freeze
+
+        # @param argv [Array<String>] command and arguments
+        # @param stdin [String] text written to the process's stdin
+        # @param cwd [String, nil] working directory (default: Dir.pwd)
+        # @param timeout [Numeric, nil] seconds before the process is killed
+        # @param env [Hash] extra environment variables
+        # @yield [String] each line of stdout
+        # @return [Result]
+        def run(argv, stdin: '', cwd: nil, timeout: nil, env: {}, &block)
+          Open3.popen3(env.to_h, *argv, chdir: cwd || Dir.pwd, pgroup: true) do |input, output, error, wait|
+            collect(input, output, error, wait, stdin:, timeout:, &block)
+          rescue TimeoutError
+            terminate(wait)
+            raise TimeoutError, "#{argv.first} did not finish within #{timeout}s"
+          end
+        rescue Errno::ENOENT => e
+          raise Error, "cannot run #{argv.first.inspect}: #{e.message}"
+        end
+
+        private
+
+        # Drives one spawned process: feeds stdin and reads stderr on their own
+        # threads, pumps stdout through a queue so each line can be yielded
+        # before the process exits, and assembles the Result once it does.
+        def collect(input, output, error, wait, stdin:, timeout:)
+          feeder = Thread.new { feed(input, stdin) }
+          errors = Thread.new { error.read }
+          queue  = Queue.new
+          reader = Thread.new { pump(output, queue) }
+          lines  = []
+          drain(queue, deadline(timeout)) do |line|
+            lines << line
+            yield line if block_given?
+          end
+          [feeder, reader].each(&:join)
+          Result.new(stdout: lines.join, stderr: errors.value.to_s, status: wait.value)
+        end
+
+        def deadline(timeout)
+          timeout && (now + timeout)
+        end
+
+        def feed(input, text)
+          input.binmode
+          input.write(text.to_s)
+        rescue Errno::EPIPE, IOError
+          nil
+        ensure
+          input.close unless input.closed?
+        end
+
+        def pump(output, queue)
+          output.each_line { |line| queue << line }
+        ensure
+          queue << EOF
+        end
+
+        # Pops lines until EOF, raising TimeoutError once the deadline passes.
+        def drain(queue, deadline)
+          loop do
+            remaining = deadline && [deadline - now, 0].max
+            line = remaining ? queue.pop(timeout: remaining) : queue.pop
+            raise TimeoutError if line.nil?
+            break if line.equal?(EOF)
+
+            yield line
+          end
+        end
+
+        def terminate(wait)
+          pgid = -wait.pid
+          Process.kill('TERM', pgid)
+          return if wait.join(GRACE_SECONDS)
+
+          Process.kill('KILL', pgid)
+          wait.join
+        rescue Errno::ESRCH, Errno::ECHILD
+          nil
+        end
+
+        def now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/copilot/session.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Copilot < Provider
+      # Decides, per completion, whether to resume the CLI session that
+      # answered the previous turn or to start a new one. A session is resumed
+      # only when the transcript RubyLLM hands over, minus the newest message,
+      # is exactly what that session already saw. A rewound, edited or cleared
+      # history gets a fresh session replayed from the whole transcript.
+      class Session
+        Plan = Data.define(:messages, :resume_id) do
+          def resume?
+            !resume_id.nil?
+          end
+        end
+
+        attr_reader :id
+
+        def initialize
+          reset!
+        end
+
+        # @param messages [Array<RubyLLM::Message>] the full RubyLLM transcript
+        # @param session_id [String, nil] a caller-chosen session to continue
+        # @param resume [Boolean] false forces a fresh session every time
+        # @return [Plan] the messages to send and the session to resume, if any
+        def plan(messages, session_id: nil, resume: true)
+          raise ArgumentError, 'no messages to send' if messages.empty?
+          return Plan.new(messages: [messages.last], resume_id: session_id) if session_id
+          return Plan.new(messages: messages, resume_id: nil) unless resume && continues?(messages)
+
+          Plan.new(messages: [messages.last], resume_id: @id)
+        end
+
+        # Remember which session answered, and what it has now seen.
+        def record(messages, reply, id:)
+          @id = id
+          @fingerprint = id ? Transcript.fingerprint(messages + [reply]) : nil
+        end
+
+        def reset!
+          @id = nil
+          @fingerprint = nil
+        end
+
+        private
+
+        def continues?(messages)
+          return false unless @id && @fingerprint && messages.size > 1
+
+          Transcript.fingerprint(messages[0...-1]) == @fingerprint
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/copilot/settings.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module RubyLLM
+  module Providers
+    class Copilot < Provider
+      # The settings for one completion. Each value comes from, in order of
+      # precedence, chat.with_provider_options(copilot: {...}), the
+      # RubyLLM.config.copilot_* option, then the default here.
+      class Settings
+        DEFAULT_COMMAND = 'copilot'
+        DEFAULT_TIMEOUT = 600
+
+        attr_reader :command, :cwd, :timeout, :args, :env, :session_id
+
+        def initialize(config, provider_options = {})
+          opts = self.class.namespaced(provider_options)
+          @command         = opts.fetch(:command) { config.copilot_command } || DEFAULT_COMMAND
+          @cwd             = opts.fetch(:cwd) { config.copilot_cwd }
+          @timeout         = self.class.positive_or_nil(opts.fetch(:timeout) { timeout_default(config) })
+          @allow_all_tools = opts.fetch(:allow_all_tools) { config.copilot_allow_all_tools }
+          @args            = self.class.split_args(opts.fetch(:args) { config.copilot_args })
+          @env             = self.class.stringify(opts.fetch(:env) { config.copilot_env })
+          @session_id      = opts[:session_id]
+          @resume          = opts.fetch(:resume) { config.copilot_resume.nil? || config.copilot_resume }
+        end
+
+        # True when the agent may run every tool without confirmation.
+        def allow_all_tools?
+          @allow_all_tools ? true : false
+        end
+
+        # False when every completion must start a fresh CLI session.
+        def resume?
+          @resume ? true : false
+        end
+
+        class << self
+          # The copilot: sub-hash of provider_options with symbol keys.
+          def namespaced(provider_options)
+            return {} unless provider_options.is_a?(Hash)
+
+            raw = provider_options[:copilot] || provider_options['copilot'] || {}
+            raise ArgumentError, 'provider_options[:copilot] must be a Hash' unless raw.is_a?(Hash)
+
+            raw.transform_keys(&:to_sym)
+          end
+
+          # A positive number of seconds, or nil for "no timeout".
+          def positive_or_nil(value)
+            return nil if value.nil?
+
+            number = Float(value)
+            number.positive? ? number : nil
+          end
+
+          # Extra CLI arguments given as an array or a shell-style string.
+          def split_args(value)
+            case value
+            when nil then []
+            when String then Shellwords.split(value)
+            else Array(value).map(&:to_s)
+            end
+          end
+
+          def stringify(value)
+            (value || {}).to_h.to_h { |key, item| [key.to_s, item.to_s] }
+          end
+        end
+
+        private
+
+        def timeout_default(config)
+          config.copilot_timeout.nil? ? DEFAULT_TIMEOUT : config.copilot_timeout
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/copilot/transcript.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+
+module RubyLLM
+  module Providers
+    class Copilot < Provider
+      # Renders RubyLLM messages into the text the CLI reads from stdin, and
+      # fingerprints transcripts so Session can tell whether a CLI session
+      # already holds the earlier turns.
+      class Transcript
+        REPLAY_PREAMBLE = "The conversation so far follows. Continue it by writing the assistant's next reply " \
+                          "to the last turn. Do not repeat the tags.\n\n"
+        EMPTY = '(empty message)'
+
+        class << self
+          def fingerprint(messages)
+            Digest::SHA256.hexdigest(JSON.generate(messages.map { |message| summary(message) }))
+          end
+
+          def summary(message)
+            {
+              role: message.role.to_s,
+              content: message.content.to_s,
+              tool_call_id: message.tool_call_id,
+              tool_calls: tool_calls(message).map { |call| [call.id, call.name, call.arguments] },
+              attachments: attachments(message).map { |attachment| attachment_note(attachment) }
+            }
+          end
+
+          # The message text plus a note per attachment naming its location;
+          # the agent can open local files with its own tools.
+          def text_of(message)
+            parts = [message.content.to_s]
+            attachments(message).each { |attachment| parts << attachment_note(attachment) }
+            parts.reject(&:empty?).join("\n").strip
+          end
+
+          def attachment_note(attachment)
+            source = attachment.respond_to?(:source) ? attachment.source : attachment
+            name = attachment.respond_to?(:filename) ? attachment.filename : nil
+            location = source.respond_to?(:to_path) ? source.to_path : source.to_s
+            "[Attached file#{" '#{name}'" if name}: #{location}]"
+          end
+
+          def attachments(message)
+            message.respond_to?(:attachments) ? Array(message.attachments) : []
+          end
+
+          def tool_calls(message)
+            calls = message.respond_to?(:tool_calls) ? message.tool_calls : nil
+            calls.respond_to?(:values) ? calls.values : Array(calls)
+          end
+        end
+
+        def initialize(messages)
+          @system, @turns = messages.partition { |message| message.role == :system }
+        end
+
+        # All system messages joined, or nil when there are none.
+        def system_prompt
+          text = @system.map { |message| self.class.text_of(message) }.reject(&:empty?).join("\n\n")
+          text.empty? ? nil : text
+        end
+
+        # A lone user turn goes through as-is; anything longer becomes a
+        # tagged replay of the conversation.
+        def prompt
+          return EMPTY if @turns.empty?
+          return single_turn if @turns.one? && @turns.first.role == :user
+
+          REPLAY_PREAMBLE + @turns.map { |message| turn(message) }.join("\n")
+        end
+
+        private
+
+        def single_turn
+          text = self.class.text_of(@turns.first)
+          text.empty? ? EMPTY : text
+        end
+
+        def turn(message)
+          body = self.class.text_of(message)
+          case message.role
+          when :tool then "<tool_result id=\"#{message.tool_call_id}\">\n#{body}\n</tool_result>"
+          when :assistant then "<assistant>\n#{body}#{tool_calls_text(message)}\n</assistant>"
+          else "<user>\n#{body}\n</user>"
+          end
+        end
+
+        def tool_calls_text(message)
+          self.class.tool_calls(message).map do |call|
+            "\n<tool_call id=\"#{call.id}\" name=\"#{call.name}\">#{JSON.generate(call.arguments)}</tool_call>"
+          end.join
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/copilot/version.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    # Version of the ruby_llm-providers-copilot gem. Kept in its own file
+    # so the gemspec can read the literal without loading the provider.
+    class Copilot < Provider
+      VERSION = '0.0.1'
+
+      def self.version
+        VERSION
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/copilot.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+require 'securerandom'
+require 'ruby_llm/providers/copilot/version'
+require 'ruby_llm/providers/copilot/errors'
+require 'ruby_llm/providers/copilot/settings'
+require 'ruby_llm/providers/copilot/command'
+require 'ruby_llm/providers/copilot/transcript'
+require 'ruby_llm/providers/copilot/session'
+require 'ruby_llm/providers/copilot/runner'
+require 'ruby_llm/providers/copilot/response'
+
+module RubyLLM
+  module Providers
+    # Copilot: the GitHub Copilot CLI agent as a RubyLLM provider.
+    #
+    # Each completion spawns `copilot` in non-interactive mode, pipes the
+    # prompt on stdin and reads its JSON event stream from stdout. The agent
+    # keeps its own tools, MCP servers and instructions and works in the
+    # current directory (or config.copilot_cwd). Multi-turn chats resume the
+    # same session (--resume) as long as the RubyLLM transcript still matches
+    # what that session has seen; otherwise a fresh session is started from
+    # the whole transcript.
+    #
+    #   require 'ruby_llm/providers/copilot'
+    #   chat = RubyLLM.chat(model: 'default', provider: :copilot)
+    #   chat.ask('Summarise the README in this directory')
+    class Copilot < Provider
+      DEFAULT_MODEL = 'default'
+      MODELS = %w[default auto].freeze
+      CAPABILITIES = %w[streaming].freeze
+
+      # Satisfies RubyLLM's protocol lookups; every request goes through
+      # #complete below, never through a wire protocol.
+      protocol :copilot, RubyLLM::Protocol
+
+      class << self
+        # Anything responding to #run like Runner; tests inject fakes here.
+        attr_accessor :runner
+
+        def configuration_options
+          %i[copilot_command copilot_cwd copilot_timeout copilot_allow_all_tools copilot_args copilot_env
+             copilot_resume]
+        end
+
+        def configuration_requirements
+          []
+        end
+
+        def local?
+          true
+        end
+
+        # Any id goes straight to --model, so there is no catalog to check.
+        def assume_models_exist?
+          true
+        end
+
+        # The agent runs its own tools; RubyLLM tools cannot be handed to it.
+        # Hosts such as aia check this before attaching tools or MCP servers.
+        def accepts_tools?
+          false
+        end
+
+        def display_name
+          'GitHub Copilot CLI'
+        end
+
+        def model_id(model)
+          model.respond_to?(:id) ? model.id : model.to_s
+        end
+
+        def effort_for(thinking)
+          return nil unless thinking.respond_to?(:effort) && thinking.effort
+
+          value = thinking.effort.to_s
+          Command::EFFORTS.include?(value) ? value : nil
+        end
+
+        def new_session_id
+          SecureRandom.uuid
+        end
+      end
+
+      attr_reader :session
+
+      def initialize(config)
+        super
+        @session = Session.new
+      end
+
+      # Never contacted; the transport layer only needs a base URL.
+      def api_base
+        'cli://copilot'
+      end
+
+      # Messages go to the CLI as text, so there is nothing to upload or
+      # convert beforehand.
+      def preprocess_messages(messages, **)
+        messages
+      end
+
+      def discard_missing_uploads(_messages, _error, **)
+        []
+      end
+
+      # :reek:LongParameterList -- the keyword set is RubyLLM's Provider#complete contract
+      def complete(messages, model:, tools: {}, provider_options: {}, schema: nil, thinking: nil,
+                   temperature: nil, max_output_tokens: nil, before_request: [], **, &block)
+        reject_tools!(tools)
+        reject_schema!(schema)
+        log_ignored(temperature:, max_output_tokens:)
+        settings   = Settings.new(@config, provider_options)
+        plan       = session.plan(messages, session_id: settings.session_id, resume: settings.resume?)
+        transcript = Transcript.new(plan.messages)
+        session_id = plan.resume_id || self.class.new_session_id
+        argv       = build_argv(settings, model, plan, session_id, thinking)
+        prompt     = if plan.resume?
+                       transcript.prompt
+                     else
+                       Command.prompt_with_instructions(transcript.prompt,
+                                                        transcript.system_prompt)
+                     end
+        before_request.each { |hook| hook.call({ argv: argv, prompt: prompt }) }
+        response   = Response.new(model: model, session_id: session_id)
+        run        = runner.run(argv, stdin: prompt, cwd: settings.cwd, timeout: settings.timeout,
+                                      env: settings.env) do |line|
+          response.ingest(line) { |chunk| block&.call(chunk) }
+        end
+        message = response.message(run)
+        session.record(messages, message, id: response.session_id)
+        message
+      end
+
+      # A static catalog: "default" sends no --model flag, "auto" lets
+      # Copilot route; any other id is passed through to --model.
+      def list_models
+        MODELS.map { |id| static_model(id) }
+      end
+
+      private
+
+      def runner
+        self.class.runner || Runner.new
+      end
+
+      def build_argv(settings, model, plan, session_id, thinking)
+        Command.new(settings).build(
+          model: self.class.model_id(model),
+          session_id: session_id,
+          resume_id: plan.resume_id,
+          effort: self.class.effort_for(thinking)
+        )
+      end
+
+      def static_model(id)
+        Model.new(
+          id: id,
+          name: "GitHub Copilot CLI (#{id})",
+          provider: slug,
+          capabilities: CAPABILITIES,
+          modalities: { input: %w[text], output: %w[text] },
+          metadata: { source: 'ruby_llm-providers-copilot' }
+        )
+      end
+
+      def reject_tools!(tools)
+        return if tools.nil? || tools.empty?
+
+        raise UnsupportedFeatureError,
+              'RubyLLM tools cannot be handed to the copilot CLI; the agent brings its own tools. ' \
+              'Remove with_tools or choose another provider.'
+      end
+
+      def reject_schema!(schema)
+        return if schema.nil?
+
+        raise UnsupportedFeatureError, 'the copilot CLI has no structured-output option; remove with_schema'
+      end
+
+      def log_ignored(**options)
+        ignored = options.compact.keys
+        return if ignored.empty?
+
+        RubyLLM.logger.debug { "copilot: ignoring #{ignored.join(', ')} (not supported by the copilot CLI)" }
+      end
+    end
+  end
+end
+
+RubyLLM::Provider.register :copilot, RubyLLM::Providers::Copilot unless RubyLLM::Provider.resolve(:copilot)

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-providers-copilot
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+  - Dewayne VanHoozer
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+  - !ruby/object:Gem::Dependency
+    name: ruby_llm
+    requirement: !ruby/object:Gem::Requirement
+      requirements:
+        -
+          - ">="
+          - !ruby/object:Gem::Version
+            version: "2.1"
+        -
+          - "<"
+          - !ruby/object:Gem::Version
+            version: "3"
+    type: :runtime
+    prerelease: false
+    version_requirements: !ruby/object:Gem::Requirement
+      requirements:
+        -
+          - ">="
+          - !ruby/object:Gem::Version
+            version: "2.1"
+        -
+          - "<"
+          - !ruby/object:Gem::Version
+            version: "3"
+description: "Adds a copilot provider to RubyLLM. Prompts are piped to the GitHub Copilot CLI's stdin and its JSON events are read back from stdout, so the agent (with its own tools, MCP servers and resumable sessions) can be used wherever RubyLLM expects a model, e.g. `--model copilot/default` in aia."
+email:
+  - dvanhoozer@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+  - CHANGELOG.md
+  - LICENSE.txt
+  - README.md
+  - lib/ruby_llm/providers/copilot.rb
+  - lib/ruby_llm/providers/copilot/command.rb
+  - lib/ruby_llm/providers/copilot/errors.rb
+  - lib/ruby_llm/providers/copilot/response.rb
+  - lib/ruby_llm/providers/copilot/runner.rb
+  - lib/ruby_llm/providers/copilot/session.rb
+  - lib/ruby_llm/providers/copilot/settings.rb
+  - lib/ruby_llm/providers/copilot/transcript.rb
+  - lib/ruby_llm/providers/copilot/version.rb
+homepage: "https://github.com/madbomber/ruby_llm-providers-copilot"
+licenses:
+  - MIT
+metadata:
+  homepage_uri: "https://github.com/madbomber/ruby_llm-providers-copilot"
+  source_code_uri: "https://github.com/madbomber/ruby_llm-providers-copilot"
+  changelog_uri: "https://github.com/madbomber/ruby_llm-providers-copilot/blob/main/CHANGELOG.md"
+  bug_tracker_uri: "https://github.com/madbomber/ruby_llm-providers-copilot/issues"
+  rubygems_mfa_required: "true"
+rdoc_options: []
+require_paths:
+  - lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+    -
+      - ">="
+      - !ruby/object:Gem::Version
+        version: "3.2"
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+    -
+      - ">="
+      - !ruby/object:Gem::Version
+        version: "0"
+requirements: []
+rubygems_version: 4.1.0.beta3
+specification_version: 4
+summary: RubyLLM provider that drives the GitHub Copilot CLI agent in non-interactive mode.
+test_files: []