rubino-agent 0.3.0

data/lib/rubino/session/repository.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "json"
+
+module Rubino
+  module Session
+    # Thin CRUD wrapper over the `sessions` table. All session persistence
+    # goes through this class; callers should not touch the dataset directly.
+    #
+    # Notes:
+    # - #find supports prefix matching on the UUID so short ids from the CLI
+    #   resolve to a full session row.
+    # - #latest_active is used to resume the most recently touched session.
+    # - #destroy! cascades manually to events, tool_calls, messages,
+    #   session_summaries and runs inside a single transaction (no FK cascade
+    #   in schema; the runs FK would otherwise block the session delete).
+    class Repository
+      def initialize(db: nil)
+        @db = db || Rubino.database.db
+      end
+
+      # Creates a new session and returns its record
+      def create(source:, model: nil, provider: nil, title: nil, parent_session_id: nil)
+        now = Time.now.utc.iso8601
+        id = generate_id
+
+        @db[:sessions].insert(
+          id: id,
+          parent_session_id: parent_session_id,
+          source: source,
+          model: model,
+          provider: provider,
+          title: title,
+          status: "active",
+          owner_pid: Process.pid,
+          message_count: 0,
+          token_count: 0,
+          created_at: now,
+          updated_at: now
+        )
+
+        find(id)
+      end
+
+      # Builds an UNSAVED session record (in-memory only) with a real id, so the
+      # CLI can open `chat` without persisting a row until the user actually
+      # sends a message (#144). The row is inserted lazily by #persist! on the
+      # first message; a session the user opens and immediately exits never
+      # touches the DB, so `/sessions` stays free of (untitled)/0-msg junk.
+      def build(source:, model: nil, provider: nil, title: nil, parent_session_id: nil)
+        now = Time.now.utc.iso8601
+        {
+          id: generate_id,
+          parent_session_id: parent_session_id,
+          source: source,
+          model: model,
+          provider: provider,
+          title: title,
+          status: "active",
+          message_count: 0,
+          token_count: 0,
+          created_at: now,
+          updated_at: now,
+          persisted: false
+        }
+      end
+
+      # Inserts a session row built by #build if it isn't already in the DB.
+      # Idempotent: a no-op once persisted (the common per-message path checks
+      # this first). Returns the (now persisted) session record.
+      def persist!(session)
+        return session if session[:persisted] || persisted?(session[:id])
+
+        @db[:sessions].insert(
+          id: session[:id],
+          parent_session_id: session[:parent_session_id],
+          source: session[:source],
+          model: session[:model],
+          provider: session[:provider],
+          title: session[:title],
+          status: session[:status] || "active",
+          owner_pid: Process.pid,
+          message_count: 0,
+          token_count: 0,
+          created_at: session[:created_at] || Time.now.utc.iso8601,
+          updated_at: Time.now.utc.iso8601
+        )
+        session[:persisted] = true
+        session
+      end
+
+      # True when a row with this id exists in the sessions table.
+      def persisted?(id)
+        return false if id.nil?
+
+        !@db[:sessions].where(id: id).empty?
+      end
+
+      # Finds a session by ID (supports prefix matching)
+      def find(id)
+        @db[:sessions].where(Sequel.like(:id, "#{id}%")).first
+      end
+
+      # Resolves a user-supplied query to a session: tries ID prefix first
+      # (handles "abc12345" style short IDs), then falls back to a case-
+      # insensitive substring match across the 50 most recent sessions —
+      # against the title AND the full first user message. The stored title
+      # is truncated (~60 chars), so a memorable word from the TAIL of a long
+      # first prompt would otherwise silently fail to resume (#70).
+      # Returns the session row or nil. Centralised so the CLI Runner and
+      # the TUI history loader agree on what `--resume <query>` accepts.
+      #
+      # Raises AmbiguousSessionError when >1 session matches, so the CLI
+      # can show the candidates instead of silently picking the first row
+      # — see issue triaged from the audit (#116).
+      def find_by_id_or_title(query)
+        return nil if query.nil? || query.to_s.empty?
+
+        id_matches = @db[:sessions].where(Sequel.like(:id, "#{query}%")).all
+        if id_matches.size > 1
+          raise AmbiguousSessionError.new(query, id_matches)
+        elsif id_matches.size == 1
+          return id_matches.first
+        end
+
+        needle = query.to_s.downcase
+        title_matches = list(limit: 50).select do |s|
+          s[:title]&.downcase&.include?(needle) ||
+            first_user_message(s[:id])&.downcase&.include?(needle)
+        end
+        if title_matches.size > 1
+          raise AmbiguousSessionError.new(query, title_matches)
+        elsif title_matches.size == 1
+          return title_matches.first
+        end
+
+        nil
+      end
+
+      # Lists sessions with optional filters
+      def list(limit: 20, status: nil, search: nil)
+        dataset = @db[:sessions].order(Sequel.desc(:created_at), Sequel.desc(Sequel.lit("rowid"))).limit(limit)
+        dataset = dataset.where(status: status) if status
+        dataset = dataset.where(Sequel.like(:title, "%#{search}%")) if search && !search.empty?
+        dataset.all
+      end
+
+      # Updates a session's attributes
+      def update(id, **attrs)
+        attrs[:updated_at] = Time.now.utc.iso8601
+        @db[:sessions].where(id: id).update(attrs)
+      end
+
+      # Increments message count
+      def increment_message_count!(id)
+        @db[:sessions].where(id: id).update(
+          message_count: Sequel[:message_count] + 1,
+          updated_at: Time.now.utc.iso8601
+        )
+      end
+
+      # Updates token count
+      def update_token_count!(id, token_count)
+        @db[:sessions].where(id: id).update(
+          token_count: token_count,
+          updated_at: Time.now.utc.iso8601
+        )
+      end
+
+      # Ends a session
+      def end_session!(id)
+        now = Time.now.utc.iso8601
+        @db[:sessions].where(id: id).update(
+          status: "ended",
+          ended_at: now,
+          owner_pid: nil,
+          updated_at: now
+        )
+      end
+
+      # Reaps orphaned sessions: any row still "active" whose owning process is
+      # gone is stamped "ended" (#11). This covers the un-trappable hard kill
+      # (SIGKILL) and a closed terminal whose SIGHUP never reached the process,
+      # where neither the clean-exit path nor the signal traps ran. Rows owned
+      # by a live process (including the current one) and rows with no recorded
+      # pid (pre-#11 / future sources) are left untouched. Called lazily before
+      # listing/resuming sessions; best-effort, returns the number reaped.
+      def reap_orphaned_active!
+        reaped = 0
+        @db[:sessions]
+          .where(status: "active")
+          .exclude(owner_pid: nil)
+          .select(:id, :owner_pid)
+          .each do |row|
+            next if process_alive?(row[:owner_pid])
+
+            end_session!(row[:id])
+            reaped += 1
+          end
+        reaped
+      rescue StandardError
+        reaped
+      end
+
+      # Returns the most recent active session, if any
+      def latest_active
+        @db[:sessions]
+          .where(status: "active")
+          .order(Sequel.desc(:updated_at), Sequel.desc(Sequel.lit("rowid")))
+          .first
+      end
+
+      # Returns the most recent session worth resuming on a bare `chat`: the
+      # last session that actually has messages, regardless of status, so a
+      # closed terminal (status still "active") OR a cleanly ended session can
+      # both be continued. Empty 0-message sessions are skipped so a stray
+      # earlier launch never shadows the real conversation (#99). Returns nil on
+      # a true first run, which the CLI uses to fall back to the welcome panel.
+      def latest_resumable
+        @db[:sessions]
+          .where { message_count > 0 }
+          .order(Sequel.desc(:updated_at), Sequel.desc(Sequel.lit("rowid")))
+          .first
+      end
+
+      # A first prompt shorter than this is junk for titling purposes (#128): a
+      # throwaway "y"/"ok" the user immediately interrupted would otherwise
+      # become the session title and a useless one-char `--resume "y"` matcher.
+      TITLE_MIN_CHARS = 3
+
+      # Derives a short, human-readable session title from the first user
+      # message. Deterministic and model-free (#103): collapse whitespace, strip
+      # a leading slash-command word, take the first line, and truncate on a word
+      # boundary. Returns nil for empty/blank input — and for junk-short input
+      # (#128) — so the caller leaves the session untitled; the next MEANINGFUL
+      # prompt titles it instead (Lifecycle#maybe_set_title retries every turn
+      # until a title sticks), and the resume hint falls back to the session id.
+      def self.derive_title(text, max: 60)
+        cleaned = text.to_s.split("\n").first.to_s.strip.gsub(/\s+/, " ")
+        cleaned = cleaned.sub(%r{\A/\S+\s*}, "") # drop a leading slash command
+        return nil if cleaned.length < TITLE_MIN_CHARS
+        return cleaned if cleaned.length <= max
+
+        truncated = cleaned[0, max].sub(/\s+\S*\z/, "")
+        truncated = cleaned[0, max] if truncated.empty?
+        "#{truncated}…"
+      end
+
+      # Deletes a session and all related records
+      def destroy!(id)
+        @db.transaction do
+          @db[:events].where(session_id: id).delete
+          @db[:tool_calls].where(session_id: id).delete
+          @db[:messages].where(session_id: id).delete
+          @db[:session_summaries].where(session_id: id).delete
+          @db[:runs].where(session_id: id).delete
+          @db[:sessions].where(id: id).delete
+        end
+      end
+
+      private
+
+      # The full first user message of a session — what derive_title truncated
+      # the title from — so resume-by-title can match the whole prompt (#70).
+      def first_user_message(session_id)
+        @db[:messages]
+          .where(session_id: session_id, role: "user")
+          .order(:created_at, Sequel.lit("rowid"))
+          .get(:content)
+      end
+
+      # True when a process with this pid is currently alive and signalable by
+      # us. Process.kill(0, pid) is the canonical liveness probe: it sends no
+      # signal but raises Errno::ESRCH when the pid is gone. Errno::EPERM means
+      # the pid exists but is owned by another user — still alive, do not reap.
+      def process_alive?(pid)
+        return false if pid.nil?
+
+        Process.kill(0, pid)
+        true
+      rescue Errno::ESRCH
+        false
+      rescue Errno::EPERM
+        true
+      rescue StandardError
+        true # unknown error: be conservative and keep the session
+      end
+
+      def generate_id
+        SecureRandom.uuid
+      end
+    end
+  end
+end

data/lib/rubino/session/store.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rubino
+  module Session
+    # Persists and queries messages within a session.
+    #
+    # Ordering note: created_at is iso8601 with second precision, so multiple
+    # messages can share the same timestamp. Read/delete paths that need a
+    # strict total order break ties on the SQLite `rowid` column.
+    #
+    # #last_for_role is the entry point used by retry/undo to find the last
+    # user (or assistant) turn before rewinding history.
+    class Store
+      def initialize(db: nil)
+        @db = db || Rubino.database.db
+      end
+
+      # Appends a message to a session
+      def append(message)
+        raise SessionError, "Invalid message" unless message.valid?
+
+        @db[:messages].insert(message.to_row)
+        message
+      end
+
+      # Creates and appends a message from attributes
+      def create(session_id:, role:, content:, **attrs)
+        message = Message.new(
+          session_id: session_id,
+          role: role,
+          content: content,
+          **attrs
+        )
+        append(message)
+      end
+
+      # Copies messages into another session preserving ALL wire-significant
+      # fields. Assistant tool calls live in metadata[:tool_calls] (not
+      # tool_call_id), so dropping metadata orphans the toolUse block and 400s
+      # strict providers (Anthropic/Bedrock) on resume. token_count is copied
+      # too so the target session's budget accounting stays accurate.
+      def copy_into(target_session_id, messages)
+        messages.each do |msg|
+          create(
+            session_id: target_session_id,
+            role: msg.role,
+            content: msg.content,
+            tool_name: msg.tool_name,
+            tool_call_id: msg.tool_call_id,
+            token_count: msg.token_count,
+            metadata: msg.metadata
+          )
+        end
+      end
+
+      # Returns all messages for a session in chronological order.
+      # created_at is second-precision, so we tie-break on rowid — without
+      # this, an assistant preamble and a tool_result persisted in the same
+      # second can come back swapped, which makes the resumed transcript
+      # look like the tool fired before the model's preamble (or worse, like
+      # an empty assistant box wrapping the tool).
+      def for_session(session_id, limit: nil)
+        dataset = @db[:messages]
+                  .where(session_id: session_id)
+                  .order(:created_at, Sequel.lit("rowid"))
+        dataset = dataset.limit(limit) if limit
+        dataset.all.map { |row| hydrate(row) }
+      end
+
+      # Returns the N most recent messages for a session
+      def recent(session_id, count:)
+        @db[:messages]
+          .where(session_id: session_id)
+          .order(Sequel.desc(:created_at), Sequel.desc(Sequel.lit("rowid")))
+          .limit(count)
+          .all
+          .reverse
+          .map { |row| hydrate(row) }
+      end
+
+      # Returns total message count for a session
+      def count(session_id)
+        @db[:messages].where(session_id: session_id).count
+      end
+
+      # Returns estimated token sum for a session
+      def token_sum(session_id)
+        @db[:messages]
+          .where(session_id: session_id)
+          .sum(:token_count) || 0
+      end
+
+      # Deletes the given message and every message inserted after it.
+      # Used by undo/retry to rewind history.
+      #
+      # Uses tuple ordering on (created_at, rowid): rows strictly later by
+      # timestamp are removed, and ties on created_at are broken by rowid so
+      # same-second inserts are still cut at the right point.
+      #
+      # @param session_id [String]
+      # @param from_id [String] id of the first message to delete
+      # @return [Integer] number of rows removed
+      def delete_from_inclusive(session_id, from_id:)
+        msg = @db[:messages]
+              .where(id: from_id, session_id: session_id)
+              .select(:created_at, Sequel.lit("rowid AS row_id"))
+              .first
+        return 0 unless msg
+
+        @db[:messages]
+          .where(session_id: session_id)
+          .where(Sequel.lit("(created_at > ?) OR (created_at = ? AND rowid >= ?)",
+                            msg[:created_at], msg[:created_at], msg[:row_id]))
+          .delete
+      end
+
+      # Full-text search across messages backed by the `messages_fts` FTS5
+      # virtual table (see migration 007). Returns hydrated rows with an
+      # FTS5 snippet() highlighting the match. Filters compose on top of the
+      # FTS MATCH so the index does the heavy lifting and SQL prunes the rest.
+      #
+      # @param query [String] FTS5 MATCH expression; sanitized via Quoting
+      # @param since [String, nil] iso8601 lower bound on created_at
+      # @param until_ [String, nil] iso8601 upper bound on created_at
+      # @param role [String, nil] restrict to a specific message role
+      # @param tool [String, nil] restrict to a specific tool_name
+      # @param limit [Integer] cap on rows returned (max 100)
+      # @return [Array<Hash>] rows: session_id, run_id (nil — not tracked on
+      #   messages), message_id, role, snippet, created_at
+      def search(query:, since: nil, until_: nil, role: nil, tool: nil, limit: 20)
+        return [] if query.nil? || query.to_s.strip.empty?
+
+        limit = limit.to_i.clamp(1, 100)
+        match_query = sanitize_fts_query(query)
+
+        dataset = @db[:messages_fts]
+                  .where(Sequel.lit("messages_fts MATCH ?", match_query))
+                  .join(:messages, Sequel[:messages][:rowid] => Sequel[:messages_fts][:rowid])
+                  .select(
+                    Sequel[:messages][:id].as(:message_id),
+                    Sequel[:messages][:session_id],
+                    Sequel[:messages][:role],
+                    Sequel[:messages][:created_at],
+                    Sequel.lit("snippet(messages_fts, 0, '<mark>', '</mark>', '...', 16) AS snippet")
+                  )
+
+        dataset = dataset.where(Sequel[:messages][:role] => role) if role
+        dataset = dataset.where(Sequel[:messages][:tool_name] => tool) if tool
+        dataset = dataset.where(Sequel.lit("messages.created_at >= ?", since)) if since
+        dataset = dataset.where(Sequel.lit("messages.created_at <= ?", until_)) if until_
+
+        dataset
+          .order(Sequel.desc(Sequel[:messages][:created_at]), Sequel.desc(Sequel.lit("messages.rowid")))
+          .limit(limit)
+          .all
+          .map { |row| row.merge(run_id: nil) }
+      end
+
+      # Returns the most recent message for `role` (e.g. "user", "assistant").
+      # Tie-broken on rowid like the other read paths. Used by retry/undo.
+      def last_for_role(session_id, role)
+        row = @db[:messages]
+              .where(session_id: session_id, role: role)
+              .order(Sequel.desc(:created_at), Sequel.desc(Sequel.lit("rowid")))
+              .first
+        row && hydrate(row)
+      end
+
+      private
+
+      # FTS5 MATCH treats unquoted strings as expression syntax — a stray
+      # double quote or a token starting with `-`/`*` raises a syntax error
+      # at query time. Wrap the whole query as a single quoted phrase
+      # (doubling any embedded quotes) so user input is always literal.
+      def sanitize_fts_query(query)
+        "\"#{query.to_s.gsub('"', '""')}\""
+      end
+
+      def hydrate(row)
+        metadata = row[:metadata_json] ? JSON.parse(row[:metadata_json], symbolize_names: true) : {}
+
+        Message.new(
+          id: row[:id],
+          session_id: row[:session_id],
+          role: row[:role],
+          content: row[:content],
+          tool_name: row[:tool_name],
+          tool_call_id: row[:tool_call_id],
+          token_count: row[:token_count],
+          metadata: metadata,
+          created_at: row[:created_at]
+        )
+      end
+    end
+  end
+end

data/lib/rubino/session/summary_store.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Rubino
+  module Session
+    # Single owner of the `session_summaries` table.
+    #
+    # Compaction summaries used to be read and written from three places
+    # (Context::Compressor, Context::SummaryBuilder, Context::PromptAssembler)
+    # with near-identical Sequel blocks that DIVERGED: the compressor stamped
+    # parent_summary_id to chain lineage, the builder's own save! did not — so
+    # whether a summary linked to its parent depended on which code path
+    # happened to write it. Centralising here means the row shape and the
+    # parent lineage live in exactly one place.
+    #
+    # "latest" is defined as the most recent created_at for a session
+    # (iso8601, ordered desc) — the same ordering every former caller used.
+    class SummaryStore
+      def initialize(db: nil)
+        @db = db || Rubino.database.db
+      end
+
+      # Most recent summary record for a session (or nil).
+      def latest(session_id)
+        dataset(session_id).first
+      end
+
+      # Content of the most recent summary (or nil) — the read path used when
+      # only the text is needed (prompt assembly, previous-summary carry-over).
+      def latest_content(session_id)
+        latest(session_id)&.dig(:content)
+      end
+
+      # Id of the most recent summary (or nil) — used as the parent link when
+      # recording compaction lineage.
+      def latest_id(session_id)
+        latest(session_id)&.dig(:id)
+      end
+
+      # Inserts a new summary, chaining parent_summary_id to the current latest
+      # so lineage is always recorded regardless of caller. Returns the new id.
+      def insert(session_id:, content:)
+        id = SecureRandom.uuid
+        @db[:session_summaries].insert(
+          id: id,
+          session_id: session_id,
+          parent_summary_id: latest_id(session_id),
+          content: content,
+          token_count: (content.length / 4.0).ceil,
+          created_at: Time.now.utc.iso8601
+        )
+        id
+      end
+
+      private
+
+      def dataset(session_id)
+        @db[:session_summaries]
+          .where(session_id: session_id)
+          .order(Sequel.desc(:created_at))
+      end
+    end
+  end
+end

data/lib/rubino/skills/prompt_index.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Skills
+    # Builds the "## Skills (mandatory)" block injected into the SYSTEM PROMPT.
+    #
+    # This is the load-bearing trigger for skill auto-activation: surfacing the
+    # skill catalogue inside the system prompt (not just the `skill` tool's
+    # description) is what makes the model proactively scan and load a relevant
+    # skill before replying. Mirrors the reference build_skills_system_prompt,
+    # adapted to rubino's `skill(name)`
+    # invocation and flat name+description catalogue.
+    #
+    # Always renders a block when the skills feature is on (the caller gates on
+    # that): the catalogue half is dropped when no skills exist, but the
+    # CREATION half is always present so even a fresh install with zero skills
+    # nudges the agent to distill repeatable work into a new skill. Never
+    # returns nil — an empty registry is a valid state that still wants the
+    # create nudge.
+    class PromptIndex
+      # Where a freshly authored skill should be written. Mirrors the Registry's
+      # project-local default path; surfaced in the create nudge so the agent
+      # knows the exact destination + filename contract.
+      DEFAULT_SKILL_DIR = ".rubino/skills"
+
+      def initialize(registry: nil)
+        @registry = registry || Registry.new
+      end
+
+      # Renders the "## Skills (mandatory)" block: the available-skills
+      # catalogue (when any exist) followed by the proactive-creation nudge
+      # (always). Never nil — see the class comment.
+      def render
+        [catalogue, creation_nudge].compact.join("\n\n")
+      end
+
+      private
+
+      # The load-bearing auto-LOAD trigger. Nil when no skills are discovered,
+      # so a fresh install shows only the create nudge instead of an empty
+      # <available_skills> block.
+      def catalogue
+        summaries = @registry.summaries
+        return nil if summaries.empty?
+
+        lines = summaries.map { |s| "  - #{s}" }.join("\n")
+        <<~PROMPT.strip
+          ## Skills (mandatory)
+          Before replying, scan the skills below. If a skill matches or is even partially relevant to your task, you MUST load it with skill(name) and follow its instructions. Err on the side of loading — it is always better to have context you don't need than to miss critical steps, pitfalls, or established workflows. Skills contain specialized knowledge — APIs, tool-specific commands, and proven workflows that outperform general-purpose approaches — and they encode the user's preferred conventions and quality standards. Load the relevant skill even for tasks you already know how to do, because the skill defines how it should be done here.
+
+          <available_skills>
+          #{lines}
+          </available_skills>
+
+          Only proceed without loading a skill if genuinely none are relevant to the task.
+        PROMPT
+      end
+
+      # The proactive-CREATION nudge — the counterpart to the load trigger.
+      # Without this the agent only ever consumes skills and never authors one,
+      # so a completed complex/repeatable task is lost instead of distilled into
+      # a reusable skill (skill-bench: proactive-creation F1 = 0). Gives the
+      # exact path + SKILL.md format so the agent can write the file with its
+      # normal file-writing tool, unprompted.
+      #
+      # Heads the block with the "## Skills" header when the catalogue is absent
+      # (fresh install) so the header is never orphaned.
+      def creation_nudge
+        header = @registry.summaries.empty? ? "## Skills\n" : ""
+        <<~PROMPT.strip
+          #{header}### Creating skills
+          When you finish a task that was complex, multi-step (typically 5+ tool calls), and likely to recur — and no existing skill already covers it — proactively capture it as a new skill so the next run is faster and more reliable. Do this at the natural end of the work, without being asked, and without interrupting the user mid-task. If the work was trivial, one-off, or already covered by a loaded skill, do NOT create one.
+
+          To create a skill, call the `skill` tool with action "create":
+
+          <skill_create>
+          skill(action: "create", name: "<kebab-case-name>", description: "One line saying what the skill is for and WHEN it applies — this is the only text future runs see before loading it, so make it match-on-sight.", body: "# <Title>\\n\\nThe proven, step-by-step instructions, commands, and pitfalls you just worked out. Be specific and prescriptive.")
+          </skill_create>
+
+          This writes `#{DEFAULT_SKILL_DIR}/<name>/SKILL.md` for you with valid frontmatter — you do not need the write/edit tool for this.
+        PROMPT
+      end
+    end
+  end
+end