gmcp 0.5.0

data/lib/gmcp/voice/chrome.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require 'openssl'
+
+module GMCP
+  module Voice
+    # Google Voice has no OAuth scope, so its session is a set of google.com
+    # cookies. GMCP reads them from the Chrome profile already signed in to the
+    # account, found by email in Chrome's Local State. Chrome keeps that
+    # session alive as it is used, so GMCP never signs in or refreshes anything
+    # itself, and an account with no Chrome profile simply has no Voice.
+    #
+    # macOS only. Chrome encrypts cookie values with AES-128-CBC under a key
+    # derived from the "Chrome Safe Storage" Keychain item; reading that item
+    # asks the user once, and "Always Allow" makes it silent thereafter.
+    module Chrome
+      class Error < StandardError; end
+
+      KEYCHAIN_SERVICE = 'Chrome Safe Storage'
+
+      # Cookie values are "v10" + AES-128-CBC(key, iv: 16 spaces). The key is
+      # PBKDF2-SHA1 of the Keychain secret, salt "saltysalt", 1003 rounds.
+      ENCRYPTED_PREFIX = 'v10'
+      # From cookie DB version 24 the plaintext starts with SHA-256(host_key).
+      HOST_DIGEST_VERSION = 24
+      # Chrome timestamps count microseconds from 1601-01-01.
+      CHROME_EPOCH_OFFSET = 11_644_473_600
+
+      QUERY = <<~SQL.tr("\n", ' ')
+        SELECT host_key, name, hex(encrypted_value) AS value, expires_utc
+        FROM cookies WHERE host_key = '.google.com' OR host_key LIKE '%.google.com'
+      SQL
+
+      class << self
+        def dir
+          File.expand_path(ENV.fetch('GMCP_CHROME_DIR', '~/Library/Application Support/Google/Chrome'))
+        end
+
+        # The account's google.com session cookies, as { name => value }.
+        def cookies(account)
+          db = File.join(profile_for(account), 'Cookies')
+          raise Error, "Chrome profile for #{account} has no cookie store" unless File.exist?(db)
+
+          version = Integer(sqlite(db, "SELECT value FROM meta WHERE key = 'version'").dig(0, 'value'))
+          now = Time.now.to_i
+          sqlite(db, QUERY)
+            .reject { |row| expired?(row['expires_utc'], now) }
+            .sort_by { |row| row['host_key'] == '.google.com' ? 1 : 0 } # the shared domain wins on a name clash
+            .to_h { |row| [row['name'], decrypt([row['value']].pack('H*'), version)] }
+        end
+
+        # The profile directory signed in as account. Chrome records each
+        # profile's Google account in Local State's info_cache.
+        def profile_for(account)
+          state = JSON.parse(File.read(File.join(dir, 'Local State')))
+          name, = state.dig('profile', 'info_cache')&.find { |_dir, info| info['user_name'].to_s.casecmp?(account) }
+          raise Error, "No Chrome profile is signed in as #{account}. Sign in to Chrome with that account." unless name
+
+          File.join(dir, name)
+        rescue Errno::ENOENT
+          raise Error, "Google Chrome is not set up here (no #{File.join(dir, 'Local State')})"
+        end
+
+        def decrypt(blob, version)
+          return blob.force_encoding(Encoding::UTF_8) unless blob.start_with?(ENCRYPTED_PREFIX)
+
+          cipher = OpenSSL::Cipher.new('aes-128-cbc').decrypt
+          cipher.key = key
+          cipher.iv = ' ' * 16
+          plain = cipher.update(blob.byteslice(ENCRYPTED_PREFIX.bytesize..)) + cipher.final
+          plain = plain.byteslice(32..) if version >= HOST_DIGEST_VERSION
+          plain.force_encoding(Encoding::UTF_8)
+        rescue OpenSSL::Cipher::CipherError
+          raise Error, 'Could not decrypt Chrome cookies; the Chrome Safe Storage key did not match'
+        end
+
+        # Test seam.
+        def reset!
+          @key = nil
+        end
+
+        private
+
+        def key
+          @key ||= begin
+            secret, status = Open3.capture2('security', 'find-generic-password', '-w', '-s', KEYCHAIN_SERVICE)
+            raise Error, "Keychain access to #{KEYCHAIN_SERVICE} was denied" unless status.success?
+
+            OpenSSL::PKCS5.pbkdf2_hmac_sha1(secret.chomp, 'saltysalt', 1003, 16)
+          end
+        end
+
+        # Read through sqlite3's immutable mode, so Chrome's own lock on the
+        # live database neither blocks the read nor is disturbed by it.
+        def sqlite(db, query)
+          out, err, status = Open3.capture3('sqlite3', '-json', "file:#{db}?mode=ro&immutable=1", query)
+          raise Error, "Could not read #{db}: #{err.strip}" unless status.success?
+
+          out.strip.empty? ? [] : JSON.parse(out)
+        end
+
+        def expired?(expires_utc, now)
+          micros = expires_utc.to_i
+          micros.positive? && (micros / 1_000_000) - CHROME_EPOCH_OFFSET < now
+        end
+      end
+    end
+  end
+end

data/lib/gmcp/voice/conversation.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module GMCP
+  module Voice
+    # A Voice thread: one counterparty's texts, or a call/voicemail record.
+    # Decoded from the positional array api2thread/list returns:
+    #
+    #   [id, read, messages, pagination_token, contacts, folders, _, is_text,
+    #    phone_numbers]
+    #
+    # Messages come newest first. Text thread ids look like "t.+<number>",
+    # call and voicemail ids like "c.<opaque>".
+    #
+    # Named Conversation rather than Thread so it never shadows ::Thread
+    # inside this namespace.
+    class Conversation
+      attr_reader :id, :messages, :phone_numbers, :names
+
+      def self.from_jspb(row)
+        return nil unless row.is_a?(Array) && row[0].is_a?(String)
+
+        new(row)
+      end
+
+      def initialize(row)
+        @id       = row[0]
+        @read     = row[1] == true
+        @messages = Array(row[2]).filter_map { |m| Message.from_jspb(m) }
+
+        contacts = Array(row[4]).map { |c| Message.split_contact(c) }
+        contacts += @messages.map { |m| [m.name, m.phone_number] }
+        @names         = contacts.map(&:first).compact.uniq
+        @phone_numbers = (Array(row[8]).grep(String) + contacts.map(&:last)).compact.uniq
+      end
+
+      def read?
+        @read
+      end
+
+      def latest
+        @messages.first
+      end
+
+      def counterparty
+        [@names.first, @phone_numbers.first].compact.join(' ').then { |s| s.empty? ? @id : s }
+      end
+
+      # Case-insensitive substring match over names, numbers and message text.
+      # A query that is mostly digits also matches on digits alone, so
+      # "555-0100" finds "+15550100".
+      def matches?(query)
+        needle = query.to_s.downcase.strip
+        return false if needle.empty?
+
+        haystack = [*@names, *@phone_numbers, *@messages.map(&:text)].compact
+        return true if haystack.any? { |s| s.downcase.include?(needle) }
+
+        digits = needle.gsub(/\D/, '')
+        return false if digits.length < 3 || needle.match?(/[a-z]/)
+
+        @phone_numbers.any? { |p| p.gsub(/\D/, '').include?(digits) }
+      end
+    end
+  end
+end

data/lib/gmcp/voice/folder.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module GMCP
+  module Voice
+    # One page of threads from api2thread/list, the endpoint voice.google.com
+    # itself uses. The request is positional:
+    #
+    #   [folder_id, threads_per_page, messages_per_thread, cursor, _, [_, 1, 1, 1]]
+    #
+    # The trailing array is what the web client always sends. The cursor is the
+    # newest-message timestamp (ms, as a string) of the last thread on the
+    # previous page; nil asks for the most recent page.
+    #
+    # The response is [threads, _, version_token].
+    class Folder
+      PAGE_SIZE           = 20
+      MESSAGES_PER_THREAD = 15
+      SEARCH_PAGES        = 10
+      MAX_SEARCH_PAGES    = 50
+
+      attr_reader :name, :conversations
+
+      def self.fetch(session, name = 'all', cursor: nil)
+        id = FOLDERS.fetch(name.to_s) do
+          raise ArgumentError, "Unknown folder: #{name}. Valid: #{FOLDERS.keys.join(', ')}"
+        end
+        body = [id, PAGE_SIZE, MESSAGES_PER_THREAD, cursor&.to_s, nil, [nil, 1, 1, 1]]
+        new(name.to_s, session.call('api2thread/list', body))
+      end
+
+      # The API has no server-side search we can call, so walk recent pages
+      # and match locally. Bounded, because the call log reaches back years
+      # and each page is a round trip.
+      def self.search(session, query, folder: 'all', pages: SEARCH_PAGES)
+        pages = pages.to_i.clamp(1, MAX_SEARCH_PAGES)
+        matches = []
+        scanned = 0
+        cursor = nil
+        pages.times do
+          page = fetch(session, folder, cursor: cursor)
+          scanned += page.conversations.size
+          matches.concat(page.conversations.select { |c| c.matches?(query) })
+          following = page.next_cursor
+          break if following.nil? || following == cursor
+
+          cursor = following
+        end
+        [matches, scanned]
+      end
+
+      def initialize(name, response)
+        @name = name
+        rows = response.is_a?(Array) && response[0].is_a?(Array) ? response[0] : []
+        @conversations = rows.filter_map { |row| Conversation.from_jspb(row) }
+      end
+
+      # Cursor for the page after this one, or nil when this page was empty.
+      def next_cursor
+        @conversations.last&.latest&.timestamp_ms&.to_s
+      end
+
+      def inspect
+        "#<Voice::Folder #{@name} (#{@conversations.size} threads)>"
+      end
+    end
+  end
+end

data/lib/gmcp/voice/message.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module GMCP
+  module Voice
+    # One call, voicemail, or text inside a Conversation, decoded from the
+    # positional (JSPB) array the API returns. Index N holds proto field N+1:
+    #
+    #   [id, timestamp_ms, destination_id, contact, type, status, transcript,
+    #    _, duration_s, text, _, media_url, coarse_type, transcript_status, mms]
+    #
+    # contact is [name, phone_number]; mms is [text, subject, attachments, ...];
+    # transcript is [confidence, [[token_bytes_base64, ...], ...]].
+    class Message
+      attr_reader :id, :timestamp_ms, :type, :name, :phone_number, :duration, :text
+
+      def self.from_jspb(row)
+        return nil unless row.is_a?(Array) && row[0].is_a?(String)
+
+        new(row)
+      end
+
+      def initialize(row)
+        @id           = row[0]
+        @timestamp_ms = integer(row[1])
+        @name, @phone_number = Message.split_contact(row[3])
+        @type         = integer(row[4])
+        @read         = integer(row[5]) == 1
+        @duration     = row[8].is_a?(Numeric) ? row[8] : nil
+        @text         = present(row[9]) || present(row[14].is_a?(Array) ? row[14][0] : nil) || transcript(row[6])
+      end
+
+      def read?
+        @read
+      end
+
+      def type_name
+        MESSAGE_TYPES.fetch(@type, "type#{@type}")
+      end
+
+      def time
+        Time.at(@timestamp_ms / 1000.0) if @timestamp_ms
+      end
+
+      # A contact is [name, phone], but either slot may be empty, so classify
+      # by content rather than trusting position for which is the number.
+      def self.split_contact(contact)
+        strings = Array(contact).grep(String).reject(&:empty?)
+        phone = strings.find { |s| s.match?(/\A\+?[\d\s().-]{3,}\z/) }
+        [(strings - [phone]).first, phone]
+      end
+
+      private
+
+      def integer(value)
+        Integer(value)
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def present(value)
+        value.is_a?(String) && !value.empty? ? value : nil
+      end
+
+      # Voicemail transcripts arrive as base64 token bytes. Anything that does
+      # not decode to valid UTF-8 is used as-is rather than dropped.
+      def transcript(raw)
+        tokens = raw.is_a?(Array) && raw[1].is_a?(Array) ? raw[1] : []
+        words = tokens.filter_map do |token|
+          bytes = token.is_a?(Array) ? token[0] : nil
+          next unless bytes.is_a?(String)
+
+          decoded = bytes.unpack1('m0').force_encoding('UTF-8')
+          decoded.valid_encoding? ? decoded : bytes
+        rescue ArgumentError
+          bytes
+        end
+        words.empty? ? nil : words.join(' ')
+      end
+    end
+  end
+end

data/lib/gmcp/voice/session.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'digest'
+
+module GMCP
+  module Voice
+    # Authenticated client for the internal Google Voice JSPB/protojson API.
+    #
+    # The "public" Google Voice API is what the voice.google.com SPA calls
+    # internally at https://clients6.google.com/voice/v1/voiceclient/...
+    # Auth is cookie-based plus a SAPISIDHASH triple Authorization header and
+    # a public API key embedded in the voice.google.com page source.
+    #
+    # No OAuth — the Google OAuth2 scope required for the token→cookie
+    # exchange (OAuthLogin) is reserved for Chromium and isn't grantable to
+    # external clients. The cookies come from the Chrome profile signed in to
+    # the account instead; see Voice::Chrome.
+    class Session
+      class AuthError      < StandardError; end
+      class OperationError < StandardError; end
+
+      API_HOST = 'https://clients6.google.com'
+      API_PATH = '/voice/v1/voiceclient/'
+      # Browser API key published in the voice.google.com page source — it is
+      # not a secret and identifies Google's own web client, not the user.
+      # Overridable because Google can rotate it at any time, and a rotation
+      # should not require editing the gem.
+      API_KEY  = ENV.fetch('GMCP_VOICE_API_KEY', 'AIzaSyDTYc1N4xiODyrQYK0Kl6g_y279LjYkrBg')
+      ORIGIN   = 'https://voice.google.com'
+
+      AUTH_FAILURE_CODES = %w[401 403].freeze
+      USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36'
+
+      # Cookies the browser sends to google.com on every request.
+      # SAPISID / __Secure-1PAPISID / __Secure-3PAPISID drive the auth hashes;
+      # SID / HSID / SSID / NID identify the session.
+      SESSION_COOKIE_NAMES = %w[
+        SID HSID SSID APISID SAPISID
+        __Secure-1PSID __Secure-3PSID
+        __Secure-1PAPISID __Secure-3PAPISID
+        __Secure-1PSIDCC __Secure-3PSIDCC
+        __Secure-1PSIDTS __Secure-3PSIDTS
+        NID
+      ].freeze
+
+      # A session for one account, from its GMCP Chrome profile.
+      def self.for(account)
+        new(cookies: Chrome.cookies(account))
+      rescue Chrome::Error => e
+        raise AuthError, e.message
+      end
+
+      # The Authorization header Google's internal APIs expect is three
+      # space-separated <tag> <ts>_<sha1(ts SP cookie SP origin)> chunks.
+      HASH_COOKIES = [
+        ['SAPISIDHASH',   'SAPISID'],
+        ['SAPISID1PHASH', '__Secure-1PAPISID'],
+        ['SAPISID3PHASH', '__Secure-3PAPISID']
+      ].freeze
+
+      def initialize(cookies:)
+        @cookies = cookies.slice(*SESSION_COOKIE_NAMES)
+        raise AuthError, 'No Google session (missing SAPISID). Sign in to Google in that Chrome profile.' unless @cookies['SAPISID']
+      end
+
+      # Call a Voice API method. `path` is something like "account/get" or
+      # "thread/batchupdateattributes". `body` is the JSPB request payload
+      # (usually an array, e.g. [] for empty, [[["id1","id2"]]] for a list).
+      # Returns the parsed JSON response.
+      def call(path, body = [])
+        uri = URI("#{API_HOST}#{API_PATH}#{path}?alt=protojson&key=#{API_KEY}")
+        req = Net::HTTP::Post.new(uri)
+        headers.each { |k, v| req[k] = v }
+        req.body = JSON.generate(body)
+
+        resp = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
+        parsed = JSON.parse(resp.body) rescue nil
+
+        unless resp.is_a?(Net::HTTPSuccess)
+          msg = parsed.is_a?(Hash) && parsed.dig('error', 'message') || resp.body.to_s[0, 300]
+          # Google rotates __Secure-*PSIDTS and friends under a long-lived
+          # process, so a rejection here usually means our snapshot of the
+          # cookies is stale rather than that the call was malformed. AuthError
+          # tells the caller to fetch a fresh session.
+          raise AuthError, "#{path}: HTTP #{resp.code} — #{msg}" if AUTH_FAILURE_CODES.include?(resp.code.to_s)
+
+          raise OperationError, "#{path}: HTTP #{resp.code} — #{msg}"
+        end
+
+        parsed
+      end
+
+      private
+
+      def headers
+        {
+          'Authorization'       => sapisidhash_header,
+          'Cookie'              => cookie_header,
+          'Content-Type'        => 'application/json+protobuf',
+          'Origin'              => ORIGIN,
+          'Referer'             => "#{ORIGIN}/",
+          'User-Agent'          => USER_AGENT,
+          'X-Goog-AuthUser'     => '0',
+          'X-Goog-Encode-Response-If-Executable' => 'base64',
+          'X-JavaScript-User-Agent' => 'google-api-javascript-client/1.1.0',
+          'X-Requested-With'    => 'XMLHttpRequest'
+        }
+      end
+
+      def sapisidhash_header
+        ts = Time.now.to_i
+        HASH_COOKIES.filter_map do |tag, name|
+          val = @cookies[name] or next
+          "#{tag} #{ts}_#{Digest::SHA1.hexdigest("#{ts} #{val} #{ORIGIN}")}"
+        end.join(' ')
+      end
+
+      def cookie_header
+        @cookies.map { |k, v| "#{k}=#{v}" }.join('; ')
+      end
+    end
+  end
+end

data/lib/gmcp/voice/tools.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require 'time'
+
+module GMCP
+  module Voice
+    # MCP tools for Google Voice.
+    #
+    # Each takes the same `account:` as the other services and is limited to
+    # GMCP_ACCOUNTS, but does not go through Server.with_account: Voice has no
+    # OAuth scope, so its session comes from the Chrome profile signed in to
+    # the account (see Voice::Chrome).
+    module Tools
+      def self.register(server)
+        register_read(server)
+        register_write(server)
+      end
+
+      def self.register_read(server)
+        ToolHelpers.define_tool(
+          server,
+          name: 'voice_account',
+          capability: 'voice.read',
+          description: 'Show the Google Voice number of an account.',
+          properties: { **ToolHelpers::ACCOUNT_PARAM }
+        ) do |account: nil|
+          Tools.guarding(account) do |acct|
+            number = Tools.account_number(acct)
+            ToolHelpers.text_response(
+              number ? "Voice number for #{acct}: #{number}"
+                     : "#{acct} has no Google Voice number."
+            )
+          end
+        end
+
+        ToolHelpers.define_tool(
+          server,
+          name: 'voice_list',
+          capability: 'voice.read',
+          description: 'List Google Voice threads (texts, calls, voicemail), newest first, 20 per page. ' \
+                       "Folders: #{FOLDERS.keys.join(', ')}. Pass the returned next_cursor to get the next page.",
+          properties: {
+            folder: { type: 'string', description: 'Folder name (default: all)' },
+            cursor: { type: 'string', description: 'next_cursor from a previous voice_list call' },
+            **ToolHelpers::ACCOUNT_PARAM
+          }
+        ) do |folder: 'all', cursor: nil, account: nil|
+          Tools.guarding(account) do |acct|
+            page = Folder.fetch(Tools.session(acct), folder, cursor: cursor)
+            lines = page.conversations.map { |c| Tools.format(c) }
+            next ToolHelpers.text_response("No threads in #{folder}.") if lines.empty?
+
+            lines << "next_cursor: #{page.next_cursor}"
+            ToolHelpers.text_response(lines.join("\n"))
+          end
+        end
+
+        ToolHelpers.define_tool(
+          server,
+          name: 'voice_search',
+          capability: 'voice.read',
+          description: 'Search recent Google Voice threads by contact name, phone number, or message text. ' \
+                       'Matches locally over the newest pages of a folder (20 threads per page), so older ' \
+                       'history is only reached by raising pages or narrowing the folder.',
+          properties: {
+            query:  { type: 'string', description: 'Text, name, or phone number to look for' },
+            folder: { type: 'string', description: "Folder to scan (default: all). One of #{FOLDERS.keys.join(', ')}" },
+            pages:  { type: 'integer', description: "Pages to scan (default: #{Folder::SEARCH_PAGES}, max: #{Folder::MAX_SEARCH_PAGES})" },
+            **ToolHelpers::ACCOUNT_PARAM
+          },
+          required: ['query']
+        ) do |query:, folder: 'all', pages: Folder::SEARCH_PAGES, account: nil|
+          Tools.guarding(account) do |acct|
+            matches, scanned = Folder.search(Tools.session(acct), query, folder: folder, pages: pages)
+            ToolHelpers.list_response(matches, empty_message: "No matches in the #{scanned} most recent #{folder} threads.") do |c|
+              Tools.format(c)
+            end
+          end
+        end
+      end
+
+      def self.register_write(server)
+        ToolHelpers.define_tool(
+          server,
+          name: 'voice_mark_read',
+          capability: 'voice.modify',
+          description: 'Mark a Google Voice thread as read. Takes a thread id from voice_list or voice_search.',
+          properties: {
+            thread_id: { type: 'string' },
+            **ToolHelpers::ACCOUNT_PARAM
+          },
+          required: ['thread_id']
+        ) do |thread_id:, account: nil|
+          Tools.guarding(account) do |acct|
+            Tools.session(acct).call('thread/updateattributes', Tools.mark_read_body(thread_id))
+            ToolHelpers.text_response("Thread #{thread_id} marked read.")
+          end
+        end
+      end
+
+      class << self
+        # One session per account, reused across calls until Google rejects it.
+        def session(account)
+          lock.synchronize { sessions[account] ||= Session.for(account) }
+        end
+
+        # Drop memoized sessions so the next call fetches fresh cookies.
+        # guarding calls this for an account on every auth failure.
+        def reset_session!(account = nil)
+          lock.synchronize { account ? sessions.delete(account) : sessions.clear }
+        end
+
+        # Voice number for an account, or nil when the account has no Voice
+        # (account/get answers NOT_FOUND). Shape of account/get is
+        # [["+1XXXXXXXXXX", ...]].
+        def account_number(account)
+          resp = session(account).call('account/get', [])
+          resp.dig(0, 0) if resp.is_a?(Array)
+        rescue Session::OperationError => e
+          raise unless e.message.include?('NOT_FOUND')
+        end
+
+        # thread/updateattributes takes the new attributes, then a second
+        # attributes record naming which fields to change, then 1. Only `read`
+        # (field 4) is set in both, so nothing else about the thread is touched.
+        # Shape taken from a working open-source Voice client, not from probing:
+        # mutations are never sent to a live account to discover their format.
+        def mark_read_body(thread_id)
+          [
+            [thread_id, nil, nil, true, nil, nil, nil, nil],
+            [nil, nil, nil, true, nil, nil, nil, nil],
+            1
+          ]
+        end
+
+        def format(conversation)
+          latest = conversation.latest
+          parts = [conversation.id, "[#{latest&.type_name || 'empty'}]", conversation.counterparty]
+          parts << latest.time.iso8601 if latest&.time
+          parts << "read=#{conversation.read?}"
+          preview = latest&.text.to_s.gsub(/\s+/, ' ').strip
+          parts << "— #{preview[0, 120]}" unless preview.empty?
+          parts.join(' ')
+        end
+
+        # Resolves the account against GMCP_ACCOUNTS and gives every voice tool
+        # one error surface, with advice the generic ToolHelpers.guarded cannot
+        # give. An auth failure also drops that account's session, so a retry
+        # re-reads the profile instead of reusing rejected cookies.
+        def guarding(account)
+          account = GMCP::Server.configured_account(account)
+          begin
+            yield account
+          rescue Session::AuthError => e
+            reset_session!(account)
+            ToolHelpers.error_response(
+              "Voice auth failed for #{account}: #{e.message}\n" \
+              "If this persists, open Google Voice in that account's Chrome profile to refresh its session."
+            )
+          rescue Session::OperationError => e
+            ToolHelpers.error_response("Voice API error: #{e.message}")
+          end
+        end
+
+        private
+
+        def sessions
+          @sessions ||= {}
+        end
+
+        def lock
+          @lock ||= Mutex.new
+        end
+      end
+    end
+  end
+end

data/lib/gmcp/voice.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module GMCP
+  module Voice
+    # Thread folders as api2thread/list numbers them. "all" is the unified
+    # Messages+Calls view, which Google caps at a few hundred recent threads;
+    # the narrower folders reach further back.
+    FOLDERS = {
+      'all'       => 1,
+      'messages'  => 2,
+      'calls'     => 3,
+      'voicemail' => 4,
+      'spam'      => 5,
+      'archived'  => 6
+    }.freeze
+
+    MESSAGE_TYPES = {
+      0  => 'missed',
+      1  => 'received',
+      2  => 'voicemail',
+      7  => 'placed',
+      10 => 'sms.received',
+      11 => 'sms.sent',
+      14 => 'placed.cancelled'
+    }.freeze
+
+    autoload :Session,       'gmcp/voice/session'
+    autoload :Message,       'gmcp/voice/message'
+    autoload :Conversation,  'gmcp/voice/conversation'
+    autoload :Folder,        'gmcp/voice/folder'
+    autoload :Tools,         'gmcp/voice/tools'
+    autoload :Chrome,        'gmcp/voice/chrome'
+  end
+end