btape 0.1.0 → 0.3.0

data/lib/btape/executor.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'monitor'
+require_relative 'duration'
+require_relative 'null_logger'
+
+module Btape
+  # Performs the parsed commands against a browser, turning any failure into a
+  # ScriptError that points back at the line it came from.
+  #
+  # It lives apart from Runner because Runner's job is the recording session
+  # around the script — the browser, the frames, the GIF — while this is the
+  # script itself, and only this grows with each new command.
+  class Executor
+    # Commands that do something at run time, and the method that does it.
+    # Output, Viewport and Set are read before the run starts and have no
+    # behaviour of their own here.
+    HANDLERS = {
+      'Goto' => :goto, 'Click' => :click, 'Type' => :enter, 'Sleep' => :pause,
+      'Screenshot' => :screenshot, 'Evaluate' => :evaluate,
+      'WaitFor' => :wait_for_element, 'WaitForJS' => :wait_for_js,
+      'Frame' => :frame, 'Press' => :press
+    }.freeze
+
+    MAIN_FRAME = 'main'
+
+    def initialize(browser:, recorder:, settings:, lock: Monitor.new, logger: NullLogger.new)
+      @browser = browser
+      # Elements and JavaScript are looked up in the current frame, which
+      # starts as the page itself and moves when a Frame command says so.
+      @target = browser
+      @recorder = recorder
+      @settings = settings
+      @lock = lock
+      @logger = logger
+    end
+
+    def call(commands)
+      commands.each do |command|
+        @logger.debug("btape: line #{command.line_number}: #{command.name}")
+        perform(command)
+      # The run's own deadline arrives asynchronously and usually lands inside
+      # a command, which would otherwise be reported as that command failing.
+      # A caller has to be able to tell "the run outlasted Set Timeout" from
+      # "this line is broken", so it goes out as it came in.
+      rescue TimeoutError
+        raise
+      rescue StandardError => e
+        raise ScriptError.new(command.line_number, "#{command.name} failed: #{e.message}")
+      end
+    end
+
+    private
+
+    # Held across each exchange with the browser, and shared with the
+    # recorder, so a screenshot taken on the recorder's thread is never in
+    # flight at the same time as a command on this one.
+    #
+    # It is deliberately not held for a whole command: Sleep and the waiting
+    # commands spend most of their time not talking to the browser at all,
+    # and holding the lock through that would leave interval recording with
+    # nothing to capture for the duration.
+    def locked(&)
+      @lock.synchronize(&)
+    end
+
+    def perform(command)
+      handler = HANDLERS[command.name]
+      send(handler, *command.arguments) if handler
+    end
+
+    def goto(url)
+      locked { @browser.go_to(url) }
+      # Whatever frame we were in belongs to the page we just left.
+      @target = @browser
+    end
+
+    # Points the following commands at an iframe, so a tape can reach an API
+    # inside it — a slide deck's own navigation, say — rather than only what
+    # the outer document exposes. Nesting works by switching again from
+    # within, and `Frame main` returns to the page.
+    def frame(selector)
+      return @target = @browser if selector == MAIN_FRAME
+
+      # Reading .frame off the node is a further exchange with the browser, so
+      # it belongs under the lock as much as the lookup that found the node.
+      node = find(selector)
+      @target = locked { node.frame } || raise("#{selector} is not a frame")
+    end
+
+    def press(key, count = '1')
+      Integer(count, 10).times { locked { @browser.keyboard.type(key.to_sym) } }
+    end
+
+    def click(selector)
+      locked { find(selector).click }
+    end
+
+    def enter(selector, text)
+      locked do
+        element = find(selector)
+        element.focus
+        element.type(text)
+      end
+    end
+
+    def pause(duration)
+      sleep(Duration.parse(duration))
+    end
+
+    def screenshot(name = nil)
+      @recorder.capture(name: name)
+    end
+
+    def evaluate(expression)
+      locked { @target.evaluate(expression) }
+    end
+
+    def wait_for_element(selector, timeout = nil)
+      wait_until(timeout, "#{selector} to appear") { element(selector) }
+    end
+
+    def wait_for_js(expression, timeout = nil)
+      wait_until(timeout, "#{expression} to be true") { evaluate(expression) }
+    end
+
+    # Polls until the block has been satisfied WaitStable times in a row. The
+    # streak matters for pages that report readiness before they have settled:
+    # a single true reading can land mid-render, several in a row cannot.
+    #
+    # A block that raises counts as not-yet-satisfied, since a page part-way
+    # through loading will happily throw on a property that is about to
+    # exist. The last error is reported if the wait times out, so a broken
+    # expression still surfaces rather than being silently polled forever.
+    def wait_until(timeout, description)
+      timeout = timeout ? Duration.parse(timeout) : @settings.wait_timeout
+      deadline = monotonic + timeout
+      stable = 0
+      failure = nil
+
+      loop do
+        satisfied = begin
+          yield
+        rescue StandardError => e
+          failure = e
+          false
+        end
+
+        stable = satisfied ? stable + 1 : 0
+        return if stable >= @settings.wait_stable
+        raise Error, timed_out(description, timeout, failure) if monotonic >= deadline
+
+        sleep(@settings.wait_interval)
+      end
+    end
+
+    def timed_out(description, timeout, failure)
+      message = "timed out after #{timeout}s waiting for #{description}"
+      failure ? "#{message} (last error: #{failure.message})" : message
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def find(selector)
+      element(selector) || raise("element not found: #{selector}")
+    end
+
+    def element(selector)
+      locked do
+        next @target.at_css(selector) unless selector.start_with?('text=')
+
+        literal = xpath_literal(selector.delete_prefix('text='))
+        @target.at_xpath("//*[normalize-space(text())=#{literal}]")
+      end
+    end
+
+    def xpath_literal(text)
+      return %("#{text}") unless text.include?('"')
+
+      parts = text.split('"', -1).map { |part| %("#{part}") }
+      "concat(#{parts.join(%q(, '"', ))})"
+    end
+  end
+end

data/lib/btape/generate_command.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'optparse'
+require_relative 'error'
+require_relative 'llm/client'
+require_relative 'llm/generator'
+require_relative 'null_logger'
+
+module Btape
+  # `btape generate` — asks a model running on this machine for a tape and
+  # writes it out, having first checked that what came back is one.
+  #
+  # It is a separate command rather than a flag on a recording because it
+  # records nothing: no browser is opened, and the answer is a file to read,
+  # edit and then run like any other tape.
+  class GenerateCommand
+    USAGE = 'Usage: btape generate [options] DESCRIPTION'
+
+    Options = Struct.new(:help, :output_path, :context_path, :client, :verbose, keyword_init: true)
+
+    def initialize(out: $stdout, err: $stderr, stdin: $stdin, generator: nil)
+      @out = out
+      @err = err
+      @stdin = stdin
+      @generator = generator
+    end
+
+    def run(argv)
+      options = Options.new(help: false, client: {}, verbose: false)
+      words = parse_options(argv, options)
+      return print_help if options.help
+
+      write(generator(options).call(description(words), context: context(options)), options)
+      0
+    end
+
+    private
+
+    def write(script, options)
+      return @out.print(script) unless options.output_path
+
+      path = File.expand_path(options.output_path)
+      File.write(path, script, encoding: Encoding::UTF_8)
+      @out.puts "Wrote #{path}"
+    end
+
+    # The description is the words left after the flags, or standard input
+    # when there are none — a paragraph about what to record is easier to
+    # write in a file, or to pipe in, than to quote on a command line.
+    def description(words)
+      return words.join(' ') unless words.empty?
+      raise Error, USAGE if @stdin.tty?
+
+      piped = @stdin.read.to_s
+      raise Error, USAGE if piped.strip.empty?
+
+      piped
+    end
+
+    def context(options)
+      return nil unless options.context_path
+
+      File.read(File.expand_path(options.context_path), encoding: Encoding::UTF_8)
+    end
+
+    def generator(options)
+      @generator || LLM::Generator.new(client: LLM::Client.new(**options.client), logger: logger(options))
+    end
+
+    def logger(options)
+      return NullLogger.new unless options.verbose
+
+      Logger.new(@err, level: Logger::DEBUG, formatter: ->(_severity, _time, _program, message) { "#{message}\n" })
+    end
+
+    def parse_options(argv, options)
+      option_parser(options).parse(argv)
+    rescue OptionParser::ParseError => e
+      raise Error, e.message
+    end
+
+    def option_parser(options)
+      OptionParser.new do |parser|
+        parser.banner = USAGE
+        parser.on('--llm-url URL', 'The OpenAI-compatible model server to ask') do |url|
+          options.client[:base_url] = url
+        end
+        parser.on('--model NAME', 'Ask for this model rather than whichever one is loaded') do |name|
+          options.client[:model] = name
+        end
+        parser.on('--temperature N', Float, 'How freely the model writes; 0.2 by default') do |value|
+          options.client[:temperature] = value
+        end
+        parser.on('--context FILE', 'Give the model this file as context: selectors, notes, markup') do |path|
+          options.context_path = path
+        end
+        parser.on('-o', '--out FILE', 'Write the tape here rather than to standard output') do |path|
+          options.output_path = path
+        end
+        parser.on('--verbose', 'Report each attempt on stderr') { options.verbose = true }
+        parser.on('-h', '--help', 'Show this message') { options.help = true }
+      end
+    end
+
+    def print_help
+      @out.puts USAGE
+      @out.puts
+      @out.puts 'Options:'
+      @out.puts '  --llm-url URL    The OpenAI-compatible model server to ask'
+      @out.puts '  --model NAME     Ask for this model rather than whichever one is loaded'
+      @out.puts '  --temperature N  How freely the model writes; 0.2 by default'
+      @out.puts '  --context FILE   Give the model this file as context: selectors, notes, markup'
+      @out.puts '  -o, --out FILE   Write the tape here rather than to standard output'
+      @out.puts '  --verbose        Report each attempt on stderr'
+      @out.puts
+      @out.puts "Defaults to #{LLM::Client::DEFAULT_BASE_URL}, which is where LM Studio serves."
+      @out.puts 'Ollama serves the same API at http://localhost:11434/v1.'
+      @out.puts 'BTAPE_LLM_URL, BTAPE_LLM_MODEL and BTAPE_LLM_KEY are used when the flags are not given.'
+      0
+    end
+  end
+end

data/lib/btape/gif_encoder.rb

@@ -2,62 +2,123 @@
 
 require 'chunky_png'
 require_relative 'lzw_compressor'
+require_relative 'palette'
 
 module Btape
-  # A deliberately small GIF89a encoder. RGB332 gives a fixed 256-colour palette,
-  # avoiding a native image or video dependency.
+  # A deliberately small GIF89a encoder, so that recording needs no native
+  # image or video dependency.
   class GifEncoder
-    def initialize(delay: 10)
-      @delay = delay
+    # A GIF frame delay is two bytes of hundredths of a second.
+    MAX_DELAY = 0xffff
+    # Eight bits per pixel: one index into a 256-colour table.
+    MIN_CODE_SIZE = "\x08"
+
+    def self.for(settings)
+      new(
+        delay: (settings.frame_delay * 100).round,
+        loop_count: settings.loop_count,
+        quantizer: settings.quantizer,
+        scale: settings.scale,
+        width: settings.output_width
+      )
+    end
+
+    def initialize(delay: 10, loop_count: 0, quantizer: :adaptive, scale: 1.0, width: nil, dedupe: true)
+      @delay = delay.clamp(1, MAX_DELAY)
+      @loop_count = loop_count
+      @quantizer = quantizer
+      @scale = scale
+      @width = width
+      @dedupe = dedupe
       @compressor = LzwCompressor.new
     end
 
-    def write(png_paths, output)
-      raise Error, 'no screenshots were captured' if png_paths.empty?
+    # Returns the GIF as a binary String. Frames are PNG paths or ChunkyPNG
+    # canvases. Callers that are not writing to the filesystem — attaching the
+    # GIF to a record, say — want this rather than a file to read back.
+    def encode(frames)
+      raise Error, 'no screenshots were captured' if frames.empty?
 
-      images = png_paths.map { |path| ChunkyPNG::Image.from_file(path) }
+      images = frames.map { |frame| resize(image(frame)) }
       width, height = images.first.dimension.to_a
       raise Error, 'captured screenshots have different dimensions' unless images.all? do |image|
         image.dimension.to_a == [width, height]
       end
 
-      File.binwrite(output, gif(images, width, height))
+      palette = Palette.build(@quantizer, images)
+      gif(collapse(images.map { |image| index(image, palette) }), width, height, palette)
+    end
+
+    # Writes to a path, or to anything that responds to write.
+    def write(frames, output)
+      data = encode(frames)
+      return output.write(data) if output.respond_to?(:write)
+
+      File.binwrite(output, data)
     end
 
     private
 
-    def gif(images, width, height)
+    def image(frame)
+      frame.is_a?(ChunkyPNG::Canvas) ? frame : ChunkyPNG::Image.from_file(frame)
+    end
+
+    def resize(image)
+      target = @width || (image.width * @scale).round
+      return image if target == image.width || target < 1
+
+      # A wide enough source rounds its scaled height down to nothing, and a
+      # zero-height canvas becomes a GIF no decoder can show.
+      height = [(image.height * target.to_f / image.width).round, 1].max
+      image.resample_bilinear(target, height)
+    end
+
+    def index(image, palette)
+      image.pixels.map { |pixel| palette.index_for(pixel) }
+    end
+
+    # A run that sits on one page for a second is a dozen identical frames.
+    # Holding the first for longer says the same thing in a fraction of the
+    # bytes, and spares a decoder the redundant frames.
+    def collapse(frames)
+      frames.each_with_object([]) do |pixels, collapsed|
+        previous = collapsed.last
+        if @dedupe && previous && previous.first == pixels
+          previous[1] = [previous[1] + @delay, MAX_DELAY].min
+        else
+          collapsed << [pixels, @delay]
+        end
+      end
+    end
+
+    def gif(frames, width, height, palette)
       data = +'GIF89a'.b
-      data << [width, height, 0b11110111, 0, 0].pack('vvCCC') << palette
-      data << "!\xFF\x0BNETSCAPE2.0\x03\x01\x00\x00\x00".b
-      images.each { |image| write_frame(data, image, width, height) }
+      data << [width, height, 0b11110111, 0, 0].pack('vvCCC') << palette.to_gct
+      data << netscape
+      frames.each { |pixels, delay| write_frame(data, pixels, delay, width, height) }
       data << ';'.b
     end
 
-    def write_frame(data, image, width, height)
-      data << "!\xF9\x04\x00".b << [@delay].pack('v') << "\x00\x00".b
-      data << ','.b << [0, 0, width, height, 0].pack('vvvvC')
-      compressed = lzw(image)
-      data << "\x08".b
-      compressed.bytes.each_slice(255) { |slice| data << slice.length.chr << slice.pack('C*') }
-      data << "\x00".b
+    # The application extension that carries the loop count. Zero loops
+    # forever, which is what an unattended recording usually wants.
+    def netscape
+      +"!\xFF\x0BNETSCAPE2.0\x03\x01".b << [@loop_count].pack('v') << "\x00".b
     end
 
-    def palette
-      (0..255).map { |i| [((i >> 5) & 7) * 255 / 7, ((i >> 2) & 7) * 255 / 7, (i & 3) * 255 / 3].pack('C3') }.join.b
+    def write_frame(data, pixels, delay, width, height)
+      data << "!\xF9\x04\x00".b << [delay].pack('v') << "\x00\x00".b
+      data << ','.b << [0, 0, width, height, 0].pack('vvvvC')
+      data << MIN_CODE_SIZE.b
+      lzw(pixels).bytes.each_slice(255) { |slice| data << slice.length.chr << slice.pack('C*') }
+      data << "\x00".b
     end
 
-    def lzw(image)
-      pixels = image.pixels.map { |pixel| rgb332(pixel) }
+    def lzw(pixels)
       codes = []
       @compressor.call(pixels) { |code, width| codes << [code, width] }
       pack_codes(codes)
     end
 
-    def rgb332(pixel)
-      (ChunkyPNG::Color.r(pixel) & 0xe0) | ((ChunkyPNG::Color.g(pixel) & 0xe0) >> 3) | (ChunkyPNG::Color.b(pixel) >> 6)
-    end
-
     def pack_codes(codes)
       buffer = 0
       count = 0

data/lib/btape/llm/client.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+require_relative '../error'
+
+module Btape
+  # Talking to a language model, which btape does for one purpose: writing a
+  # tape from a description of the recording someone wants.
+  module LLM
+    # Raised when the model, or the server in front of it, could not answer.
+    class Error < Btape::Error; end
+
+    # A chat client for an OpenAI-compatible server. Nothing here knows which
+    # one it is talking to: LM Studio, Ollama, llama.cpp's server and vLLM all
+    # answer `/v1/chat/completions` in the same shape, so pointing `--llm-url`
+    # at one of them is the whole of the configuration.
+    #
+    # The defaults assume the model is running on this machine, where there is
+    # usually no key to send and no reason for the request to leave it.
+    class Client
+      # LM Studio's; Ollama serves the same API on 11434.
+      DEFAULT_BASE_URL = 'http://localhost:1234/v1'
+      DEFAULT_TEMPERATURE = 0.2
+      # A local model on a CPU answers in tens of seconds rather than the
+      # hundreds of milliseconds a hosted one would take.
+      DEFAULT_TIMEOUT = 300
+
+      # How much of a server's error body to quote back. Enough to name the
+      # problem, not so much that a stack trace fills the terminal.
+      ERROR_BODY_LIMIT = 500
+
+      attr_reader :base_url
+
+      def initialize(base_url: nil, model: nil, api_key: nil, temperature: nil, timeout: nil)
+        @base_url = (base_url || ENV.fetch('BTAPE_LLM_URL', DEFAULT_BASE_URL)).chomp('/')
+        @model = model || ENV.fetch('BTAPE_LLM_MODEL', nil)
+        @api_key = api_key || ENV.fetch('BTAPE_LLM_KEY', nil)
+        @temperature = temperature || DEFAULT_TEMPERATURE
+        @timeout = timeout || DEFAULT_TIMEOUT
+      end
+
+      # Sends the conversation and returns the reply's text.
+      def complete(messages)
+        payload = { model: model, messages: messages, temperature: @temperature, stream: false }
+        body = post('/chat/completions', payload)
+        content = body.dig('choices', 0, 'message', 'content')
+        # Not every server answers with a String there: some hand back the
+        # content as a list of parts, and a reasoning model may answer with
+        # nothing but its thoughts. Both are this client's error to report,
+        # rather than a NoMethodError from inside it.
+        raise Error, "#{@base_url} answered without a message" unless content.is_a?(String) && !content.strip.empty?
+
+        content
+      end
+
+      # The model to ask for. A server hosting one model still wants to be
+      # told which, and the name differs with every download — so when nobody
+      # has said, the loaded one is asked for by name.
+      def model
+        @model ||= first_loaded_model
+      end
+
+      private
+
+      def first_loaded_model
+        entry = get('/models')['data']&.first
+        name = entry['id'] if entry.is_a?(Hash)
+        raise Error, "no model is loaded at #{@base_url}; load one, or name it with --model" unless name
+
+        name
+      end
+
+      def post(path, payload)
+        request = Net::HTTP::Post.new(url_for(path))
+        request['content-type'] = 'application/json'
+        request.body = JSON.generate(payload)
+        send_request(request)
+      end
+
+      def get(path)
+        send_request(Net::HTTP::Get.new(url_for(path)))
+      end
+
+      def url_for(path)
+        URI.parse("#{@base_url}#{path}")
+      end
+
+      def send_request(request)
+        request['authorization'] = "Bearer #{@api_key}" if @api_key
+        response = transport(request.uri).request(request)
+        parse(response)
+      # A local server generating a long answer is the one most likely to be
+      # killed part way through it, and the connection dropping is how that
+      # arrives here.
+      rescue IOError, Errno::ECONNRESET, Errno::EPIPE, Net::HTTPBadResponse
+        raise Error, "#{@base_url} closed the connection before answering; did the model run out of memory?"
+      # Everything else the network can say — refused, unreachable, no such
+      # host, a route that went away — is the same thing to whoever ran the
+      # command, and it is worth naming the address they can go and check.
+      rescue SocketError, SystemCallError => e
+        raise Error, "could not reach a model server at #{@base_url} (#{e.message}); is it running?"
+      # Net::OpenTimeout and Net::ReadTimeout are both Timeout::Errors, so
+      # this covers a server that accepted the connection and then thought
+      # about it for too long as well as one that never accepted it.
+      rescue Timeout::Error
+        raise Error, "#{@base_url} did not answer within #{@timeout}s"
+      end
+
+      def transport(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == 'https'
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+        http
+      end
+
+      def parse(response)
+        body = begin
+          JSON.parse(response.body.to_s)
+        rescue JSON::ParserError
+          nil
+        end
+        raise Error, failure_message(response, body) unless response.is_a?(Net::HTTPSuccess)
+        raise Error, "#{@base_url} answered with something that is not JSON" if body.nil?
+
+        body
+      end
+
+      # An OpenAI-compatible server reports its own failures as
+      # `{"error": {"message": ...}}`, and the ones that do not are quoted as
+      # they came so the reason is not lost to the status code alone.
+      def failure_message(response, body)
+        detail = body.is_a?(Hash) ? (body.dig('error', 'message') || body['error']) : nil
+        detail = response.body.to_s.strip[0, ERROR_BODY_LIMIT] if detail.nil? || detail.to_s.empty?
+        "#{@base_url} answered #{response.code}#{": #{detail}" unless detail.to_s.empty?}"
+      end
+    end
+  end
+end

data/lib/btape/llm/generator.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative '../error'
+require_relative '../null_logger'
+require_relative '../parser'
+require_relative 'client'
+require_relative 'prompt'
+
+module Btape
+  module LLM
+    # Turns a description of a recording into a tape, by asking a model for
+    # one and then holding it to the language: what comes back is parsed
+    # before it is handed on, and a reply that does not parse goes back with
+    # the parser's complaint attached.
+    #
+    # That loop is the point of generating a tape rather than pasting one out
+    # of a chat window. A small local model reliably invents a command or
+    # forgets a quote; it just as reliably fixes it when told which line.
+    class Generator
+      ATTEMPTS = 3
+
+      # Models are told not to fence their answer, and fence it anyway.
+      FENCED = /```[\w+-]*\n(.*?)```/m
+
+      def initialize(client: Client.new, attempts: ATTEMPTS, logger: NullLogger.new)
+        @client = client
+        @attempts = attempts
+        @logger = logger
+      end
+
+      # Returns the tape as a String. Raises LLM::Error if the model could not
+      # be reached, or would not produce a tape that parses.
+      def call(description, context: nil)
+        raise Error, 'nothing was said about what to record' if description.to_s.strip.empty?
+
+        messages = [
+          { role: 'system', content: Prompt.system },
+          { role: 'user', content: Prompt.user(description.strip, context: context) }
+        ]
+        attempt(messages)
+      end
+
+      private
+
+      def attempt(messages)
+        reason = nil
+        @attempts.times do |index|
+          @logger.debug("btape: asking #{@client.model} for a tape (attempt #{index + 1} of #{@attempts})")
+          script = extract(@client.complete(messages))
+          reason = fault(script)
+          return script if reason.nil?
+
+          @logger.debug("btape: the tape did not parse (#{reason}); asking again")
+          messages += [{ role: 'assistant', content: script }, { role: 'user', content: Prompt.repair(reason) }]
+        end
+        raise Error, "the model did not write a tape that parses, after #{@attempts} attempts: #{reason}"
+      end
+
+      # Why this is not a tape, or nil when it is one. The parser answers most
+      # of it; Output is checked here because it is the one requirement that
+      # belongs to the script as a whole rather than to any line of it, and a
+      # tape without it fails at the start of a recording instead.
+      #
+      # A second Output is worth another round too: the runner takes the first
+      # and says nothing about the rest, so a model that wrote two would
+      # otherwise be told it had got it right while half of what it wrote was
+      # quietly dropped.
+      def fault(script)
+        commands = Parser.new.parse(script)
+        return 'it contained no commands' if commands.empty?
+
+        outputs = commands.count { |command| command.name == 'Output' }
+        return 'it has no Output line, so there is nowhere for the GIF to go' if outputs.zero?
+        return "it has #{outputs} Output lines, and a run writes one GIF" if outputs > 1
+
+        nil
+      rescue ScriptError => e
+        e.message
+      end
+
+      # The tape out of the reply. A fenced block is taken as the answer and
+      # any prose around it dropped; everything else is passed through whole,
+      # so that a stray sentence reaches the parser and comes back as
+      # something the model is asked to fix.
+      def extract(reply)
+        match = FENCED.match(reply)
+        "#{(match ? match[1] : reply).strip}\n"
+      end
+    end
+  end
+end