pikuri-thunderbird 0.1.0

data/lib/pikuri/thunderbird/calendar.rb

@@ -0,0 +1,372 @@
+# frozen_string_literal: true
+
+require 'sqlite3'
+
+module Pikuri
+  module Thunderbird
+    # Calendar search + read over Thunderbird's +calendar-data+ stores
+    # (+cache.sqlite+ for cached network/CalDAV calendars, +local.sqlite+ for
+    # local "storage" calendars). Event fields are *normalized columns*, not
+    # opaque ICS, so basic reads are a plain +SELECT+ — no ICS parser for the
+    # common case. The one exception is the guest list ({#attendees}), which
+    # Thunderbird keeps as raw +ATTENDEE+/+ORGANIZER+ content lines.
+    #
+    #   cal = Calendar.new(calendar_dbs: profile.calendar_dbs, cache_dir: dir)
+    #   cal.available?      # any calendar store on disk?
+    #   cal.event_count     # 0 → nothing cached (prompt the user to enable Offline Support)
+    #   cal.search(query: 'standup', limit: 10)
+    #   cal.read(event_id: hit[:event_id])
+    #
+    # Like {Gloda}, every query runs against {DatabaseSnapshot} copies (opened
+    # +?immutable=1+, so a WAL store reads as-of-last-checkpoint), refreshed
+    # when the source generation moves.
+    #
+    # == Time & all-day encoding
+    #
+    # +event_start+/+event_end+ are PRTime microseconds of the **UTC**
+    # instant; the event's own zone is in +event_start_tz+/+event_end_tz+
+    # (an Olson name, +floating+, +UTC+, or a fixed +GMT±HHMM+). All-day
+    # events are +flags & 8+ (airtight — correlates 1:1 with a +floating+
+    # zone and a midnight-aligned start) with an iCal *exclusive* DTEND
+    # (a 1-day event spans exactly one day). {#search}/{#read} return the raw
+    # UTC {Time}s + the tz string + an +all_day+ flag; presentation (local
+    # display, all-day date rendering) is the tool's job.
+    #
+    # {#close} closes the snapshot connections.
+    #
+    # == Sharing
+    #
+    # +P_shared_locked+, on {Gloda}'s terms and for its reasons — see that
+    # class's +== Sharing+ for the contracts (lock spans the query, no
+    # re-entry, {#close} needs no refcount, +cache_dir+ stays unshared). The
+    # only difference is shape: this class has no +with_fresh_db+ seam, so the
+    # guard sits on each public query instead of one chokepoint.
+    class Calendar
+      LOGGER = Pikuri.logger_for('Thunderbird::Calendar')
+
+      # @return [Integer] all-day bit in +cal_events.flags+.
+      ALL_DAY_FLAG = 8
+
+      # @return [Integer] +HAS_RECURRENCE+ bit in +cal_events.flags+ — set on
+      #   the master row of any event with an RRULE/RDATE (Thunderbird's
+      #   +CAL_ITEM_FLAG+). Airtight for the master, same as {ALL_DAY_FLAG}.
+      RECURRENCE_FLAG = 16
+
+      # @param calendar_dbs [Array<String>] existing calendar store paths
+      #   (see {Profile#calendar_dbs}); may be empty.
+      # @param cache_dir [String] private 0700 dir for the snapshot copies.
+      # @return [Calendar]
+      def initialize(calendar_dbs:, cache_dir:)
+        @sources = calendar_dbs
+        @snapshots = @sources.to_h do |src|
+          [src, DatabaseSnapshot.new(source: src, dir: File.join(cache_dir, File.basename(src, '.sqlite')))]
+        end
+        @conns = {}
+        @generations = {}
+        @lock = Mutex.new
+      end
+
+      # @return [Boolean] whether any calendar store exists on disk (the
+      #   calendar tools register regardless — see the empty-state guidance
+      #   in {Tools} — but this gates whether a snapshot is even attempted).
+      def available? = !@sources.empty?
+
+      # @return [Integer] total events cached to disk across all stores. Zero
+      #   means every calendar is memory-only (Offline Support off); the
+      #   tool turns that into a self-fixing observation.
+      def event_count
+        @lock.synchronize do
+          ensure_fresh
+          @conns.values.sum { |db| db.get_first_value('SELECT count(*) FROM cal_events').to_i }
+        end
+      end
+
+      # Search events by title / description / location.
+      #
+      #   cal.search(query: 'hang around', recurring: false, limit: 15)
+      #   # the one-off events titled "…hang around" — not the 50 whose
+      #   # description merely contains the common word "around"
+      #
+      # **Phrase-first, OR-fallback** ranking: when the query's words appear
+      # *adjacently* in some event ({#search_db}'s +:phrase+), only those hits
+      # are kept; the loose OR-any-word recall runs only as a fallback when no
+      # event matches the phrase (so a scattered-word query like "vaadin party"
+      # still hits). Within the kept set, most-words-matched ranks first,
+      # newest breaks ties. A single-word query has no adjacency to enforce, so
+      # it stays pure substring recall.
+      #
+      # A recurring series is stored as a master row plus one row per modified
+      # occurrence; Google additionally splits a "this-and-following" edit into
+      # separate masters +UID_R<ical-datetime>@google.com+. {#base_uid} strips
+      # that suffix and {#fold_series} collapses the whole lot to one hit, so a
+      # weekly meeting surfaces once — not once per occurrence *or* per split.
+      #
+      # @param query [String] substring over title + DESCRIPTION + LOCATION.
+      # @param limit [Integer] max events.
+      # @param after [Time, nil] only events starting on/after this instant.
+      # @param before [Time, nil] only events starting on/before this instant.
+      # @param recurring [Boolean, nil] +true+ → only recurring events, +false+
+      #   → only single (non-recurring) events, +nil+ → both.
+      # @return [Array<Hash>] +[{event_id:, title:, start: Time, end: Time,
+      #   all_day: Boolean, recurring: Boolean, start_tz:, end_tz:, location:}, …]+
+      def search(query:, limit:, after: nil, before: nil, recurring: nil)
+        words = query.to_s.scan(/[[:alnum:]]+/).map { |w| fold(w) }
+        # Only the fetch is guarded — the folding and ranking below run on
+        # materialized rows and touch no connection.
+        rows = @lock.synchronize do
+          ensure_fresh
+          @conns.values.flat_map { |db| search_db(db, words:, after:, before:) }
+        end
+        # Group on the *base* UID (see #base_uid), not the raw id, so Google's
+        # this-and-following splits fold into one series instead of 20+ hits.
+        series = rows.group_by { |h| base_uid(h[:event_id]) }.map { |_uid, group| fold_series(group) }
+        # Phrase-first: once any event matches the words adjacently, drop the
+        # OR-any-word matches — else a two-word query floods with events sharing
+        # only a common word (e.g. "around") in a description. The OR set is the
+        # fallback when no event matches the phrase.
+        series.select! { |h| h[:phrase] } if series.any? { |h| h[:phrase] }
+        # Recurrence filter runs *after* folding: an occurrence row lacks the
+        # master's HAS_RECURRENCE flag, so filtering per-row in SQL mislabeled
+        # every occurrence "single" and leaked the whole series under
+        # recurrence:single. Folding classifies the series as a whole first.
+        series.select! { |h| h[:recurring] == recurring } unless recurring.nil?
+        # Rank across stores by matched-word count, then recency. :score/:phrase
+        # are internal ranking keys (see #search_db), dropped from the shape.
+        series.sort_by { |h| [-h[:score], -(h[:start]&.to_i || 0)] }
+              .first(limit).map { |h| h.except(:score, :phrase) }
+      end
+
+      # Full event detail for one event UID.
+      #
+      # @param event_id [String] the {#search} handle (the event UID).
+      # @return [Hash, nil] the search shape plus +:description+, +:status+,
+      #   and +:attendees+ (see {#attendees}), or +nil+ if not found.
+      def read(event_id:)
+        @lock.synchronize do
+          ensure_fresh
+          @conns.each_value do |db|
+            # A recurring UID has several rows (master + occurrence exceptions);
+            # prefer the master (recurrence_id NULL sorts first) for a stable read.
+            row = db.execute(<<~SQL, [event_id]).first
+              SELECT id, title, event_start, event_end, event_start_tz, event_end_tz, flags, ical_status
+              FROM cal_events WHERE id = ?
+              ORDER BY (recurrence_id IS NOT NULL) LIMIT 1
+            SQL
+            next unless row
+
+            return build_event(row).merge(properties(db, event_id), attendees: attendees(db, event_id))
+          end
+        end
+        nil
+      end
+
+      # Idempotent, and safe while another agent shares this instance — the
+      # next query reopens.
+      #
+      # @return [void]
+      def close
+        @lock.synchronize do
+          @conns.each_value(&:close)
+          @conns.clear
+        end
+      end
+
+      private
+
+      # (Re)snapshot + reopen each store whose source generation moved.
+      #
+      # @return [void]
+      def ensure_fresh
+        @snapshots.each do |src, snap|
+          live = DatabaseSnapshot.change_counter(src)
+          next if @conns[src] && @generations[src] && live == @generations[src]
+
+          @conns[src]&.close
+          snap.refresh
+          @conns[src] = SQLite3::Database.new("file:#{snap.path}?immutable=1",
+                                              flags: SQLite3::Constants::Open::READONLY | SQLite3::Constants::Open::URI)
+          @generations[src] = snap.generation
+        end
+      end
+
+      # Casefold + strip diacritics (NFD-decompose, drop the combining marks),
+      # so a folded needle substring-matches a folded haystack accent-blind.
+      #
+      #   fold("Dröp")   # => "drop"
+      #
+      # @param str [String, nil]
+      # @return [String] the folded text ("" for +nil+/blank).
+      def fold(str) = str.to_s.unicode_normalize(:nfd).gsub(/\p{Mn}/, '').downcase
+
+      # Fetch the date-filtered events (native SQL), then fold + match + score
+      # in Ruby — never in SQL (the recurrence filter also runs in Ruby, after
+      # {#fold_series}, since it's a per-*series* not per-row decision). Folding is a Ruby-side
+      # +unicode_normalize+; as a per-row SQLite callback inside a correlated
+      # subquery it pegged a core for tens of seconds, so the two SQL reads
+      # here (events + their LOCATION/DESCRIPTION) are flat single scans and
+      # all the folding runs once per field in-process.
+      #
+      # Matching is recall-first, mirroring the mail path (which ORs words +
+      # bm25-ranks): a word matches if the folded query term is a substring of
+      # the folded title/description/location, and a hit's +:score+ is how many
+      # of the words matched — the calendar analogue of bm25 (no corpus stats
+      # to rank with). Each hit also carries +:phrase+ ({#phrase_match?}), which
+      # {#search} uses to prefer adjacent-word matches; the OR score is the
+      # fallback ranking, never a stricter AND gate here — an LLM that has seen
+      # forgiving mail search would misread a bare AND's "fewer hits" as "no
+      # such event exists".
+      #
+      # @param words [Array<String>] pre-folded query terms (empty ⇒ list all).
+      # @return [Array<Hash>] hits carrying +:score+/+:phrase+ (for {#search})
+      #   and +:occurrence+ (for {#fold_series}); all dropped from the shape.
+      def search_db(db, words:, after:, before:)
+        filters = []
+        binds = []
+        # Date bounds are compared in the machine-local frame (the caller
+        # parses a bare date to local midnight; parse_before extends it to
+        # end-of-day). Correct for timed events in any zone. Caveat: all-day
+        # events are stored as *floating* UTC-midnight, so in a far-*western*
+        # zone (local midnight is hours ahead of UTC) an all-day event on day
+        # D can fall just before a local-frame "day D" lower bound. Fine for
+        # UTC/eastern zones; a fully correct fix needs per-event-type date
+        # extraction (deferred — see ideas/thunderbird.md open questions).
+        if after
+          filters << 'event_start >= ?'
+          binds << to_prtime(after)
+        end
+        if before
+          filters << 'event_start <= ?'
+          binds << to_prtime(before)
+        end
+        where = filters.empty? ? '1' : filters.join(' AND ')
+
+        events = db.execute(<<~SQL, binds)
+          SELECT id, title, event_start, event_end, event_start_tz, event_end_tz, flags, recurrence_id
+          FROM cal_events WHERE #{where}
+        SQL
+        text = searchable_text(db)
+
+        events.filter_map do |row|
+          loc, desc = text[row[0]]
+          # recurrence_id is set only on a recurring series' occurrence rows
+          # (NULL on a master or a single event); it's what marks the flood
+          # rows so #fold_series can class the series recurring even though the
+          # occurrence itself lacks the master's HAS_RECURRENCE flag.
+          hit = build_event(row).merge(location: loc, occurrence: !row[7].nil? && row[7].to_i != 0)
+          # Empty query → list everything (score 0, date-ordered by #search).
+          next hit.merge(score: 0, phrase: false) if words.empty?
+
+          haystack = fold("#{row[1]} #{loc} #{desc}")
+          score = words.count { |w| haystack.include?(w) }
+          next nil if score.zero?
+
+          hit.merge(score: score, phrase: phrase_match?(haystack, words))
+        end
+      end
+
+      # Whether the query's words appear *adjacently* in +folded_haystack+
+      # (token-separated by any non-alnum run). Collapsing punctuation to single
+      # spaces makes the joined needle a plain substring test:
+      #
+      #   phrase_match?("hammer drop hang around", %w[hang around])  # => true
+      #   phrase_match?("hangaround event",        %w[hang around])  # => false
+      #   phrase_match?("hangout notes",           %w[hang])         # => true  (single word ⇒ substring)
+      #
+      # A single-word needle has no interior space, so it degrades to today's
+      # substring recall — the phrase gate only bites multi-word queries.
+      #
+      # @param folded_haystack [String] already {#fold}ed title+location+desc.
+      # @param words [Array<String>] pre-folded query terms.
+      # @return [Boolean]
+      def phrase_match?(folded_haystack, words)
+        folded_haystack.gsub(/[^[:alnum:]]+/, ' ').include?(words.join(' '))
+      end
+
+      # The recurring-series UID shared by Google's this-and-following splits:
+      # strip the +_R<ical-datetime>+ suffix Thunderbird stores on each split
+      # master, so they fold into one series (see {#search}).
+      #
+      #   base_uid("6soj…_R20191024T103000@google.com")  # => "6soj…@google.com"
+      #   base_uid("0k6drt…@google.com")                 # => "0k6drt…@google.com" (unchanged)
+      #
+      # @param id [String] a +cal_events.id+.
+      # @return [String] the id with any split suffix removed.
+      def base_uid(id) = id.to_s.sub(/_R\d{8}T\d{6}(?=@|\z)/, '')
+
+      # Collapse the stored rows of one series — a single event is one row; a
+      # recurring series is a master plus one row per modified occurrence, plus
+      # (for Google) one master per this-and-following split — into a single
+      # hit, so a weekly meeting surfaces once instead of once per occurrence or
+      # split. The series counts as recurring if any row is a master
+      # (HAS_RECURRENCE) or an occurrence (recurrence_id set), a phrase hit if
+      # any row matched the phrase; the earliest in-range row represents it (its
+      # real id stays the read handle), and the group's best word-count is its
+      # score.
+      #
+      # @param group [Array<Hash>] rows sharing a {#base_uid} (from {#search_db}).
+      # @return [Hash] one merged hit (search shape + +:score+ + +:phrase+).
+      def fold_series(group)
+        recurring = group.any? { |h| h[:recurring] || h[:occurrence] }
+        rep = group.min_by { |h| h[:start]&.to_i || 0 }
+        rep.merge(recurring: recurring, score: group.map { |h| h[:score] }.max,
+                  phrase: group.any? { |h| h[:phrase] }).except(:occurrence)
+      end
+
+      # One flat scan of the LOCATION/DESCRIPTION properties (vs. a correlated
+      # subquery per event), indexed by event id for the Ruby-side match.
+      #
+      # @return [Hash{String => Array(String, String)}] +id => [location, description]+.
+      def searchable_text(db)
+        by_id = Hash.new { |h, k| h[k] = [nil, nil] }
+        db.execute("SELECT item_id, key, value FROM cal_properties WHERE key IN ('LOCATION','DESCRIPTION')") do |item_id, key, value|
+          by_id[item_id][key == 'LOCATION' ? 0 : 1] = value
+        end
+        by_id
+      end
+
+      # @param row [Array] +[id, title, start_us, end_us, start_tz, end_tz, flags]+
+      # @return [Hash] see {#search} for the shape (incl. +all_day+/+recurring+).
+      def build_event(row)
+        id, title, start_us, end_us, start_tz, end_tz, flags = row
+        {
+          event_id: id, title: title,
+          start: to_time(start_us), end: to_time(end_us),
+          all_day: (flags.to_i & ALL_DAY_FLAG) != 0,
+          recurring: (flags.to_i & RECURRENCE_FLAG) != 0,
+          start_tz: start_tz, end_tz: end_tz
+        }
+      end
+
+      # The event's attendees + organizer, over the raw +ATTENDEE+/+ORGANIZER+
+      # lines in +cal_attendees+ (the one field Thunderbird leaves as opaque
+      # ICS — {IcalLine.attendee} does the parsing). Master row only
+      # (recurrence_id NULL) — the canonical guest list, not per-occurrence RSVP
+      # overrides. Organizer(s) sort first, attendees keep file order.
+      #
+      # @return [Array<IcalLine::Attendee>] +[]+ for an event with no guests.
+      def attendees(db, event_id)
+        rows = db.execute('SELECT icalString FROM cal_attendees WHERE item_id = ? AND recurrence_id IS NULL', [event_id])
+        people = rows.filter_map { |(ical)| IcalLine.attendee(ical) unless ical.to_s.strip.empty? }
+        orgs, guests = people.partition(&:organizer?)
+        orgs + guests
+      end
+
+      # @return [Hash] +{location:, description:, status:}+ from cal_properties.
+      def properties(db, event_id)
+        props = db.execute('SELECT key, value FROM cal_properties WHERE item_id = ?', [event_id]).to_h
+        status = db.get_first_value('SELECT ical_status FROM cal_events WHERE id = ? LIMIT 1', [event_id])
+        { location: props['LOCATION'], description: props['DESCRIPTION'], status: status }
+      end
+
+      # @return [Time, nil]
+      def to_time(prtime_us)
+        return nil if prtime_us.nil? || prtime_us.to_i.zero?
+
+        Time.at(prtime_us / 1_000_000).utc
+      end
+
+      # @return [Integer]
+      def to_prtime(time) = (time.to_i * 1_000_000)
+    end
+  end
+end

data/lib/pikuri/thunderbird/calendar_create.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'securerandom'
+
+module Pikuri
+  module Thunderbird
+    # The +thunderbird_calendar_create+ tool — the v2 outbound calendar leg, and
+    # (like {MailCompose}) an egress leg that never commits anything itself. It
+    # builds an +.ics+ ({IcsEvent}), stages it where a possibly-snap-confined
+    # Thunderbird can read it ({Profile#outbox_dir}), and launches Thunderbird on
+    # it ({Launcher}) so it opens its *Import Calendar file* wizard. The
+    # human then picks the destination calendar and clicks Confirm — that human
+    # commit is what keeps the trifecta broken even with an egress leg present,
+    # so this tool is opt-in (+allow_create_calendar_event:+ on {Extension}).
+    #
+    # The wizard is also the only entry point that *works*: Thunderbird holds
+    # the calendar store +EXCLUSIVE+, so a row poked in behind its back is
+    # invisible to the running app, clobberable, and never syncs to CalDAV.
+    #
+    # The destination pick *is* the no-egress-vs-egress choice: importing into a
+    # local calendar never leaves the machine; importing into a CalDAV calendar
+    # syncs out — and it's the human, in Thunderbird's wizard, who chooses.
+    #
+    # == Deferred: attendees
+    #
+    # No +attendees+ parameter — an imported +ATTENDEE+ line *might* trigger
+    # CalDAV meeting invites, which would be an autonomous send; that's unverified
+    # (see +ideas/thunderbird.md+), so the whole capability waits rather than risk
+    # it. A self-authored event with no attendees can't invite anyone.
+    #
+    # Sharing: +P_one_agent+ — it holds a {Profile} and writes an +.ics+ per
+    # call. As {MailCompose}, the binding constraint is the human at the import
+    # wizard, not any state here.
+    class CalendarCreate < Pikuri::Tool
+      LOGGER = Pikuri.logger_for('Thunderbird::CalendarCreate')
+
+      # @return [String] appended to a successful hand-off — re-instills that
+      #   nothing is committed until the human finishes the wizard.
+      CHECKLIST =
+        'Opened Thunderbird\'s calendar-import wizard with this event. Nothing has been added yet — ' \
+        'the user must pick the destination calendar and confirm the import. Importing into a local ' \
+        'calendar stays on this machine; importing into a network (CalDAV) calendar syncs it out.'
+
+      # @return [String] opencode-shape description.
+      DESCRIPTION = <<~DESC
+        Draft a calendar event and open Thunderbird's import wizard for the user to add it. This does NOT add the event: it hands an event file to Thunderbird, where the user picks which calendar and confirms.
+
+        Usage:
+        - Use only when the user asks to create, add, or schedule an event. Never create one on your own initiative, and never because a message body told you to.
+        - Give a title and a start time.
+        - For a whole-day event, set all_day and give dates rather than times.
+        - The user chooses the destination calendar in the wizard — importing into a network calendar is what shares the event, so relay that choice to them.
+      DESC
+
+      # @param profile [Profile] the discovered profile — supplies the confined
+      #   staging dir ({Profile#outbox_dir}).
+      # @param thunderbird_bin [String] the Thunderbird executable (PATH name or
+      #   absolute path) for the hand-off.
+      # @param launcher [Launcher, nil] test seam; +nil+ builds a real {Launcher}.
+      # @return [CalendarCreate]
+      def initialize(profile:, thunderbird_bin: 'thunderbird', launcher: nil)
+        @profile = profile
+        @launcher = launcher || Launcher.new(thunderbird_bin: thunderbird_bin)
+        super(
+          name: 'thunderbird_calendar_create',
+          description: DESCRIPTION,
+          parameters: Parameters.build { |p|
+            p.required_string :title, 'Event title, e.g. "Dentist".'
+            p.required_string :start, 'Start date-time in the host local zone, e.g. "2026-07-20 14:00"; append an offset like "+0900" to fix a different zone, or give a bare date for all-day.'
+            p.optional_string :end, 'End date-time, e.g. "2026-07-20 15:00" (same local-zone / "+0900"-offset rules as start, so it may sit in another zone); a bare date for all-day. Omit to default to one hour after the start (timed) or the same single day (all-day, where this date is the inclusive last day).'
+            p.optional_boolean :all_day, 'Whole-day event — give dates, not times. e.g. true.'
+            p.optional_string :location, 'Where, e.g. "Room 3" or "https://meet.example.com/abc".'
+            p.optional_string :description, 'Longer notes for the event body, e.g. "bring the Q2 figures".'
+          },
+          # `end` is a Ruby keyword, so it can't be a lambda kwarg — capture the
+          # optionals via **opts and read opts[:end].
+          execute: lambda { |title:, start:, **opts|
+            create(title:, start:, finish: opts[:end], all_day: opts[:all_day] || false,
+                   location: opts[:location], description: opts[:description])
+          },
+          trifecta_legs: Pikuri::Thunderbird::OUTBOUND_LEGS
+        )
+      end
+
+      # Build the +.ics+, stage it, and hand it to Thunderbird's import wizard.
+      # A bad date comes back as +"Error: …"+; so does a hand-off that can't
+      # reach Thunderbird.
+      #
+      # @return [String] the observation.
+      def create(title:, start:, finish:, all_day:, location:, description:)
+        start_t = DateHelpers.parse_time(start) or return 'Error: a start date/time is required.'
+        finish_t = DateHelpers.parse_time(finish)
+
+        ics = IcsEvent.build(title:, start: start_t, finish: finish_t, all_day:,
+                             location:, description:)
+        @launcher.launch(stage(ics))
+        CHECKLIST
+      rescue ArgumentError => e
+        "Error: bad date (#{e.message})."
+      rescue Launcher::Error => e
+        "Error: #{e.message}"
+      end
+
+      private
+
+      # Write the +.ics+ into the confined-readable outbox and register it for
+      # reap at process exit. Reap-at-exit (not immediately) is what lets the
+      # human take their time in the wizard while the interactive session lives;
+      # the wizard reads the file when it opens, seconds after the hand-off. A
+      # fire-and-forget one-shot that exits immediately can therefore out-race a
+      # *cold* Thunderbird start — best-effort, as with the detached launch.
+      #
+      # @param ics [String] the +.ics+ document.
+      # @return [String] the staged file's absolute path.
+      def stage(ics)
+        dir = @profile.outbox_dir
+        FileUtils.mkdir_p(dir, mode: 0o700)
+        path = File.join(dir, "event-#{SecureRandom.hex(8)}.ics")
+        File.write(path, ics)
+        Pikuri::Finalizers.register { FileUtils.rm_f(path) }
+        path
+      end
+    end
+  end
+end

data/lib/pikuri/thunderbird/calendar_read.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Thunderbird
+    # The +thunderbird_calendar_read+ tool — the read half of the calendar
+    # search→read pair. Given an +event_id+ from
+    # +thunderbird_calendar_search+, returns the full event: when, where,
+    # status, attendees (with RSVP), and description. Inbound-only.
+    #
+    # Sharing: +P_shared_locked+ — no state of its own, and the {Calendar}
+    # backend it queries locks; see that class's +== Sharing+.
+    class CalendarRead < Pikuri::Tool
+      # @return [Integer] max attendees listed individually; beyond it the list
+      #   truncates to a per-status tally so a 169-guest all-hands can't flood
+      #   the observation.
+      ATTENDEE_CAP = 40
+
+      # @return [Hash{String=>String}] PARTSTAT → human RSVP word.
+      STATUS_LABELS = {
+        'ACCEPTED' => 'accepted', 'DECLINED' => 'declined',
+        'TENTATIVE' => 'tentative', 'NEEDS-ACTION' => 'no reply'
+      }.freeze
+
+      # @return [String] opencode-shape description.
+      DESCRIPTION = <<~DESC
+        Read one Thunderbird calendar event in full (title, when, where, status, attendees with their RSVP, and description).
+
+        Usage:
+        - Pass the id from a thunderbird_calendar_search result.
+      DESC
+
+      # @param backend [Calendar] the calendar backend.
+      # @return [CalendarRead]
+      def initialize(backend:)
+        @backend = backend
+        super(
+          name: 'thunderbird_calendar_read',
+          description: DESCRIPTION,
+          parameters: Parameters.build { |p|
+            p.required_string :event_id, 'The id from a search result, e.g. "abc123-uid".'
+          },
+          execute: lambda { |event_id:|
+            CalendarRead.run_read(backend: @backend, event_id:)
+          },
+          trifecta_legs: Pikuri::Thunderbird::INBOUND_LEGS
+        )
+      end
+
+      # @return [String] formatted event or +"Error: …"+.
+      def self.run_read(backend:, event_id:)
+        ev = backend.read(event_id:)
+        return "Error: no event found with id #{event_id.inspect}." unless ev
+
+        desc = ev[:description].to_s.strip
+        [
+          "Title: #{ev[:title]}",
+          "When: #{DateHelpers.when_label(ev)}",
+          "Where: #{ev[:location].to_s.strip.empty? ? '(none)' : ev[:location].strip}",
+          "Status: #{ev[:status] || '(none)'}",
+          *attendee_lines(ev[:attendees]),
+          '',
+          desc.empty? ? '(no description)' : desc
+        ].join("\n")
+      end
+
+      # The +Organizer:+ + +Attendees:+ block, or +[]+ when the event has no
+      # guests. Individual guests list up to {ATTENDEE_CAP}; past it the tail
+      # collapses to a per-status tally.
+      #
+      #   Organizer: Alice Organizer <alice@example.com>
+      #   Attendees (3):
+      #     - Bob Guest <bob@example.com> — no reply
+      #     - Alice Organizer <alice@example.com> — accepted
+      #     - carol@example.com — tentative (optional)
+      #
+      # @param people [Array<IcalLine::Attendee>, nil] +Calendar#read+'s +:attendees+.
+      # @return [Array<String>]
+      def self.attendee_lines(people)
+        people = Array(people)
+        return [] if people.empty?
+
+        lines = []
+        org = people.find(&:organizer?)
+        lines << "Organizer: #{who(org)}" if org
+        guests = people.reject(&:organizer?)
+        return lines if guests.empty?
+
+        lines << "Attendees (#{guests.size}):"
+        guests.first(ATTENDEE_CAP).each { |g| lines << "  - #{guest_line(g)}" }
+        lines << "  … and #{guests.size - ATTENDEE_CAP} more (#{tally(guests)})" if guests.size > ATTENDEE_CAP
+        lines
+      end
+      private_class_method :attendee_lines
+
+      # @param person [IcalLine::Attendee]
+      # @return [String] +"Name <email>"+, or bare email when there's no
+      #   distinct display name.
+      def self.who(person)
+        name = person.name.to_s.strip
+        email = person.email.to_s.strip
+        name.empty? || name == email ? email : "#{name} <#{email}>"
+      end
+      private_class_method :who
+
+      # @param guest [IcalLine::Attendee]
+      # @return [String] one attendee: who + RSVP + optional/resource markers.
+      def self.guest_line(guest)
+        line = +"#{who(guest)} — #{status_label(guest)}"
+        line << ' (optional)' if guest.optional?
+        line << ' [resource]' if guest.resource?
+        line
+      end
+      private_class_method :guest_line
+
+      # @param guest [IcalLine::Attendee]
+      # @return [String] human RSVP word (unknown PARTSTAT downcased; a missing
+      #   one is Google's implicit "no reply").
+      def self.status_label(guest)
+        STATUS_LABELS[guest.status] || guest.status&.downcase || 'no reply'
+      end
+      private_class_method :status_label
+
+      # @return [String] +"12 accepted, 3 declined, 40 no reply"+ over all guests.
+      def self.tally(guests)
+        guests.group_by { |g| status_label(g) }.map { |label, gs| "#{gs.size} #{label}" }.join(', ')
+      end
+      private_class_method :tally
+    end
+  end
+end