rubino-agent 0.3.0

data/lib/rubino/security/hardline_guard.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Security
+    # Hardline (unconditional) blocklist — a floor BELOW yolo.
+    #
+    # Commands so catastrophic they must NEVER run via the agent, regardless
+    # of --yolo, skip-approvals mode, a permissions:allow rule, or a
+    # command_allowlist entry. Opting into yolo is the user trusting the agent
+    # to move fast on their files and services — NOT trusting it to wipe the
+    # disk or power the box off.
+    #
+    # The list is deliberately TINY: only things with no recovery path —
+    # filesystem destruction rooted at / (or ~), raw block-device overwrites,
+    # filesystem format, kernel shutdown/reboot, and fork-bomb / kill-all DoS.
+    # Recoverable-but-costly operations (git reset --hard, rm -rf /tmp/x,
+    # chmod -R 777, curl|sh) DO NOT belong here — they stay in the dangerous-
+    # pattern layer where yolo/approval can pass them through. Adding anything
+    # recoverable here is a false-positive that blocks legitimate work.
+    #
+    # Mirrors the reference approval module: HARDLINE_PATTERNS,
+    # detect_hardline_command, the sudo-stdin guard, and the
+    # "tiny, no recovery path" guidance.
+    module HardlineGuard
+      # Start-of-command anchor: matches positions where a shell begins
+      # parsing a new command (start of string, after a separator, after a
+      # subshell opener), optionally consuming leading wrappers (sudo, env
+      # VAR=VAL, exec/nohup/setsid/time) so we don't false-positive on
+      # "echo reboot" or "grep shutdown log". Mirrors approval.py:_CMDPOS.
+      CMDPOS = /(?:^|[;&|\n`]|\$\()\s*(?:sudo\s+(?:-\S+\s+)*)?(?:env\s+(?:\w+=\S*\s+)*)?(?:(?:exec|nohup|setsid|time)\s+)*\s*/.source.freeze
+
+      # [regex, human description]. Matched against the lowercased, whitespace-
+      # normalized command. KEEP TINY — unrecoverable only.
+      HARDLINE_PATTERNS = [
+        # rm -r/-rf targeting the root filesystem (/ or /*)
+        [%r{\brm\s+(?:-\S*\s+)*(?:/|/\*)(?:\s|$)}, "recursive delete of root filesystem"],
+        # rm -r/-rf targeting a protected system directory
+        [%r{\brm\s+(?:-\S*\s+)*(?:/home|/root|/etc|/usr|/var|/bin|/sbin|/boot|/lib)(?:/\*)?(?:\s|$)},
+         "recursive delete of system directory"],
+        # rm targeting the home directory (~ or $HOME)
+        [%r{\brm\s+(?:-\S*\s+)*(?:~|\$home)(?:/?|/\*)?(?:\s|$)}, "recursive delete of home directory"],
+        # Filesystem format
+        [/\bmkfs(?:\.[a-z0-9]+)?\b/, "format filesystem (mkfs)"],
+        # dd to a raw block device
+        [%r{\bdd\b[^\n]*\bof=/dev/(?:sd|nvme|hd|mmcblk|vd|xvd|disk|loop)[a-z0-9]*}, "dd to raw block device"],
+        # Redirect to a raw block device (echo x > /dev/sda)
+        [%r{>\s*/dev/(?:sd|nvme|hd|mmcblk|vd|xvd|disk|loop)[a-z0-9]*\b}, "redirect to raw block device"],
+        # chmod/chown -R on the root filesystem
+        [%r{\b(?:chmod|chown)\s+(?:-\S*\s+)*-\S*r\S*\s+\S+\s+/(?:\s|$)}, "recursive chmod/chown of root filesystem"],
+        # Fork bomb (classic shell form, whitespace-tolerant)
+        [/:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/, "fork bomb"],
+        # Kill every process on the system
+        [/\bkill\s+(?:-\S+\s+)*-1\b/, "kill all processes"],
+        # System shutdown / reboot / halt / poweroff (anchored to cmd position)
+        [/#{CMDPOS}(?:shutdown|reboot|halt|poweroff)\b/, "system shutdown/reboot"],
+        [/#{CMDPOS}init\s+[06]\b/, "init 0/6 (shutdown/reboot)"],
+        [/#{CMDPOS}systemctl\s+(?:poweroff|reboot|halt|kexec)\b/, "systemctl poweroff/reboot"],
+        [/#{CMDPOS}telinit\s+[06]\b/, "telinit 0/6 (shutdown/reboot)"]
+      ].freeze
+
+      # sudo -S without a configured SUDO_PASSWORD is the model piping a
+      # *guessed* password via stdin — a brute-force vector. Unconditional
+      # block. Mirrors approval.py:_check_sudo_stdin_guard (:255).
+      SUDO_STDIN_RE = /(?:^|[;&|`\n]|&&|\|\||\$\()\s*sudo\s+-s\b/
+
+      module_function
+
+      # Returns [true, description] when the command hits the hardline floor
+      # (a HARDLINE_PATTERN or the sudo-stdin guard), else [false, nil].
+      def detect(command)
+        normalized = normalize(command)
+        HARDLINE_PATTERNS.each do |regex, description|
+          return [true, description] if normalized.match?(regex)
+        end
+        return [true, "sudo password guessing via stdin (sudo -S)"] if sudo_stdin?(normalized)
+
+        [false, nil]
+      end
+
+      # Convenience predicate for the post-approval defense-in-depth check in
+      # ShellTool. Returns the description, or nil when the command is clear.
+      def block_reason(command)
+        blocked, description = detect(command)
+        blocked ? description : nil
+      end
+
+      # sudo -S only fires the guard when no SUDO_PASSWORD is configured —
+      # with one set, an internal transform legitimately injects -S elsewhere.
+      def sudo_stdin?(normalized)
+        return false if ENV.key?("SUDO_PASSWORD")
+
+        normalized.match?(SUDO_STDIN_RE)
+      end
+
+      # Minimal normalization: collapse runs of spaces/tabs (newlines kept so
+      # the command-separator anchors still fire), trim, and lowercase so
+      # trivial obfuscation (extra spaces, case) doesn't slip through.
+      # Deliberately NOT a full ANSI/Unicode normalizer — over-engineering for
+      # the hardline floor.
+      def normalize(command)
+        command.to_s.gsub(/[ \t]+/, " ").strip.downcase
+      end
+    end
+  end
+end

data/lib/rubino/security/pattern_matcher.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Security
+    # Pattern-based permission matcher supporting wildcards.
+    # Matches tool names, commands, and file paths against configured rules.
+    #
+    # Rules format in config:
+    #   permissions:
+    #     "git *": "allow"
+    #     "shell rm -rf *": "deny"
+    #     "file_system write ~/.env": "deny"
+    #     "shell bundle *": "allow"
+    #
+    # Actions: "allow", "ask", "deny"
+    class PatternMatcher
+      ACTIONS = %w[allow ask deny].freeze
+
+      def initialize(rules: {})
+        @rules = parse_rules(rules)
+      end
+
+      # Returns the action for a given tool call description
+      # Returns :allow, :ask, or :deny
+      def match(tool_name, command_or_args = nil)
+        full_string = [tool_name, command_or_args].compact.join(" ")
+
+        # Check rules from most specific to least specific
+        @rules.each do |pattern, action|
+          return action.to_sym if matches_pattern?(full_string, pattern)
+        end
+
+        # Default: no explicit match
+        nil
+      end
+
+      # Returns true if the pattern matches the input
+      def matches_pattern?(input, pattern)
+        # Convert glob-style pattern to regex
+        regex_str = Regexp.escape(pattern)
+                          .gsub('\*', ".*")
+                          .gsub('\?', ".")
+        regex = Regexp.new("\\A#{regex_str}\\z", Regexp::IGNORECASE)
+        input.match?(regex)
+      end
+
+      private
+
+      def parse_rules(rules)
+        return {} unless rules.is_a?(Hash)
+
+        # Sort by specificity: more specific patterns first
+        # (longer patterns without wildcards are more specific)
+        rules.sort_by do |pattern, _|
+          specificity = pattern.length
+          specificity -= 10 if pattern.include?("*")
+          -specificity
+        end.to_h
+      end
+    end
+  end
+end

data/lib/rubino/security/prefix_deriver.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Security
+    # Derives the REUSABLE rule that an approval should be remembered as,
+    # instead of pinning memory to the exact "<tool>:<command>" string.
+    #
+    # Mirrors the reference persistence unit: approve_session/is_approved key on a
+    # PATTERN KEY, not the raw command.
+    # For a dangerous command the pattern key IS the dangerous description, so
+    # approving it once covers the whole risk class for the session. For a plain
+    # command the reference allowlist is prefix-ish; we derive a leading-token prefix
+    # the same way CommandAllowlist matches (start_with?, command_allowlist.rb).
+    #
+    # Pure derivation — no I/O, no persistence. Returns a small immutable Rule.
+    #
+    #   kind == :pattern  -> remember a dangerous-pattern CLASS  (value = key)
+    #   kind == :prefix   -> remember a command PREFIX           (value = "git")
+    #   kind == :command  -> remember one EXACT command          (value = "git status")
+    module PrefixDeriver
+      Rule = Struct.new(:kind, :value, keyword_init: true) do
+        # Does this remembered rule cover `command`? Matching mirrors the
+        # storage shape: a pattern covers any sibling of its class, a prefix
+        # covers any command that start_with? it (like CommandAllowlist), an
+        # exact command covers only itself.
+        def covers?(command)
+          cmd = command.to_s
+          case kind
+          when :pattern then DangerousPatterns.detect(cmd)[1] == value
+          when :prefix  then cmd.strip.start_with?(value.to_s.strip)
+          else               cmd.strip == value.to_s.strip
+          end
+        end
+      end
+
+      # Wrapper commands whose first sub-token is part of the meaningful
+      # prefix ("bundle exec" / "npm run"), not the argument. Without this a
+      # naive "first token" prefix would collapse `bundle exec rspec` and
+      # `bundle install` into the same `bundle` rule.
+      WRAPPERS = {
+        "bundle" => %w[exec].freeze,
+        "npm" => %w[run].freeze,
+        "yarn" => %w[run].freeze,
+        "pnpm" => %w[run].freeze,
+        "rake" => [].freeze,
+        "cargo" => %w[run].freeze
+      }.freeze
+
+      module_function
+
+      # Builds the rule a (tool, command) approval should be remembered as.
+      #
+      # @param pattern_key [String, nil] the dangerous description when the
+      #   caller has already detected one; we re-detect when absent so callers
+      #   that only have the raw command still get a :pattern rule.
+      def rule_for(tool:, command:, pattern_key: nil)
+        cmd = command.to_s
+        key = pattern_key || DangerousPatterns.detect(cmd)[1]
+        return Rule.new(kind: :pattern, value: key) if key
+
+        # The :prefix rule ("allow `<head>` commands") only makes sense for the
+        # shell tool, where sibling commands genuinely share a leading
+        # executable (git status / git diff). For structured-arg tools the
+        # "command" is a file path (write/edit/read) or a code/arg fragment
+        # (ruby), so a derived prefix is nonsense — "allow `output.txt`
+        # commands", "allow `6` commands". Remember those by exact command
+        # instead, so the CLI/web offer no bogus prefix choice. (B6)
+        return command_rule(tool: tool, command: cmd) unless tool.to_s == "shell"
+
+        prefix = command_prefix(cmd)
+        return command_rule(tool: tool, command: cmd) if prefix.empty?
+
+        Rule.new(kind: :prefix, value: prefix)
+      end
+
+      # The NARROW rule used by :session / :always_command for S3 so behavior
+      # stays stable: a dangerous command remembers its pattern class (matching
+      # the reference), everything else remembers the exact command. The broad :prefix
+      # rule is derivable via rule_for but only wired into a decision in S5.
+      def narrow_rule_for(tool:, command:, pattern_key: nil)
+        cmd = command.to_s
+        key = pattern_key || DangerousPatterns.detect(cmd)[1]
+        return Rule.new(kind: :pattern, value: key) if key
+
+        command_rule(tool: tool, command: cmd)
+      end
+
+      def command_rule(tool:, command:)
+        value = command.to_s.strip
+        value = tool.to_s if value.empty?
+        Rule.new(kind: :command, value: value)
+      end
+
+      # Leading safe-token run of a plain command:
+      #   "git status"            -> "git"
+      #   "bundle exec rspec"     -> "bundle exec"
+      #   "npm run test --watch"  -> "npm run"
+      # A plain command keeps only its head; a wrapper command (bundle/npm/...)
+      # additionally keeps its declared verb (exec/run) so distinct wrapped
+      # tools don't collapse into one rule. The run stops at the first flag or
+      # argument-shaped token, mirroring CommandAllowlist's start_with? match.
+      def command_prefix(command)
+        tokens = command.to_s.strip.split(/\s+/)
+        return "" if tokens.empty?
+
+        head = tokens.first
+        prefix = [head]
+
+        if WRAPPERS.key?(head)
+          verb = tokens[1]
+          prefix << verb if verb && plain_word?(verb) && WRAPPERS[head].include?(verb)
+        end
+
+        prefix.join(" ")
+      end
+
+      # A "plain word" is a bare token: not a flag, no path/assignment/glob
+      # punctuation — the shape that can safely extend a prefix.
+      def plain_word?(token)
+        token.match?(/\A[A-Za-z0-9_:.-]+\z/) && !token.start_with?("-")
+      end
+    end
+  end
+end

data/lib/rubino/security/readonly_commands.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Rubino
+  module Security
+    # Built-in auto-allow layer for provably READ-ONLY shell commands.
+    #
+    # Sits at the same decision step as the user command allowlist
+    # (ApprovalPolicy step 6) — BELOW the hardline floor and permissions:deny,
+    # which always run first, and ABOVE the confirm-policy prompt. A command
+    # auto-allows ONLY when the ENTIRE line parses as safe:
+    #
+    #   - every chain segment (split on |, &&, ||, ;, newline) starts with a
+    #     command from the read-only set (or approvals.readonly_commands);
+    #   - no output redirection (>, >>, 2>; `tee` is simply not in the set),
+    #     no command substitution ($(...) or backticks, live contexts only —
+    #     single-quoted text is literal and stays allowed), no process
+    #     substitution (<(...), >(...)), no backgrounding (&);
+    #   - no leading variable assignments (FOO=bar cmd → prompt);
+    #   - no mutating flags on otherwise-safe heads (find -exec/-delete/...,
+    #     date -s, tree -o, git --output);
+    #   - git only with a read-only subcommand, conservatively flag-checked;
+    #   - no DangerousPatterns match on the whole line (defense-in-depth for
+    #     user-extended sets).
+    #
+    # Anything the scanner cannot prove safe FAILS CLOSED to the normal
+    # approval prompt — never to silent execution. Pure functions, no I/O.
+    module ReadonlyCommands
+      # Read-only command heads auto-allowed by default. Conservative: each
+      # entry must be side-effect-free for ANY argument list once the flag
+      # checks below pass. `git` is handled separately (per-subcommand).
+      SAFE_COMMANDS = %w[
+        ls pwd find cat head tail grep rg wc file stat du df which
+        whoami date tree echo
+      ].freeze
+
+      # git subcommands that never mutate the repository. `remote` is
+      # restricted further below (bare or -v only — `git remote add` mutates),
+      # `branch` to pure-flag listing forms (`git branch foo` CREATES a branch).
+      GIT_READONLY_SUBCOMMANDS = %w[status log diff show rev-parse blame].freeze
+      GIT_BRANCH_READONLY_FLAGS = %w[
+        -a -r -v -vv --list --all --remotes --show-current --verbose
+        --merged --no-merged --color --no-color
+      ].freeze
+
+      # Mutating/executing flags that disqualify an otherwise-safe head.
+      # Matched as exact token or `flag=value`.
+      FORBIDDEN_FLAGS = {
+        "find" => %w[-exec -execdir -ok -okdir -delete -fprintf -fprint -fprint0 -fls],
+        "date" => %w[-s --set],
+        "tree" => %w[-o]
+      }.freeze
+
+      # Leading `FOO=bar cmd` environment assignment — rejected, not stripped:
+      # an assignment can change what the command resolves to (PATH=...) or
+      # how it behaves, so it is never "provably read-only".
+      ASSIGNMENT_RE = /\A[A-Za-z_][A-Za-z0-9_]*=/
+
+      module_function
+
+      # True when the ENTIRE command line is provably read-only. `extra` is
+      # the approvals.readonly_commands config: command names or leading-token
+      # prefixes ("jq", "docker ps") merged into the built-in set.
+      def auto_allowed?(command, extra: [])
+        return false if DangerousPatterns.dangerous?(command)
+
+        segments = split_segments(command.to_s)
+        return false if segments.nil? || segments.empty?
+
+        segments.all? { |segment| safe_segment?(segment, extra: extra) }
+      end
+
+      # Splits a command line into chain segments (|, ||, &&, ;, newline),
+      # quote-aware. Returns nil — reject — on any construct that could smuggle
+      # a write or an execution: redirection (>), backgrounding (&), command
+      # substitution ($( or backtick in a live context), process substitution
+      # (<( / >( )), comments, trailing backslash, unterminated quotes. Plain
+      # `<` input redirection stays allowed. Single-quoted text is literal in
+      # POSIX shells, so substitutions inside it are safe to keep.
+      def split_segments(command)
+        segments = []
+        current = +""
+        i = 0
+        while i < command.length
+          char = command[i]
+          succ = command[i + 1]
+          case char
+          when "'", "\""
+            quoted = consume_quoted(command, i, char)
+            return nil unless quoted
+
+            current << quoted
+            i += quoted.length
+            next
+          when "\\"
+            return nil if succ.nil?
+
+            current << char << succ
+            i += 1
+          when "`", ">", "#"
+            return nil
+          when "$", "<"
+            return nil if succ == "("
+
+            current << char
+          when ";", "\n", "|", "&"
+            advance = flush_segment(char, succ, segments, current)
+            return nil unless advance
+
+            current = +""
+            i += advance
+            next
+          else
+            current << char
+          end
+          i += 1
+        end
+        segments << current
+        segments.map(&:strip).reject(&:empty?)
+      end
+
+      # Flushes the segment ended by a chain operator and returns how many
+      # characters the operator consumes (2 for && and ||, 1 otherwise), or
+      # nil for a lone & — backgrounding is never provably read-only.
+      def flush_segment(char, succ, segments, current)
+        return nil if char == "&" && succ != "&"
+
+        segments << current
+        "|&".include?(char) && succ == char ? 2 : 1
+      end
+
+      # Consumes the quoted region opening at `start`. Returns the full
+      # substring including both quotes, or nil when the quote is unterminated
+      # or — for double quotes, where substitutions stay LIVE — when it
+      # contains $( or a backtick. Single-quoted text is literal in POSIX
+      # shells, so anything inside is safe to keep verbatim.
+      def consume_quoted(command, start, quote)
+        i = start + 1
+        while i < command.length
+          char = command[i]
+          if quote == "\""
+            return nil if char == "`" || (char == "$" && command[i + 1] == "(")
+
+            if char == "\\"
+              i += 2
+              next
+            end
+          end
+          return command[start..i] if char == quote
+
+          i += 1
+        end
+        nil
+      end
+
+      # One pipeline segment: tokenize (Shellwords — a parse error rejects),
+      # refuse leading assignments, then require the head to be a safe command
+      # whose flags pass the per-command checks, or an `extra` config entry.
+      def safe_segment?(segment, extra: [])
+        tokens = Shellwords.split(segment)
+        return false if tokens.empty? || tokens.first.match?(ASSIGNMENT_RE)
+
+        head = tokens.first
+        return safe_git?(tokens) if head == "git"
+        return safe_flags?(head, tokens) if SAFE_COMMANDS.include?(head)
+
+        extra_match?(tokens, extra)
+      rescue ArgumentError
+        false # unbalanced quotes etc. — fall through to the prompt
+      end
+
+      def safe_flags?(head, tokens)
+        forbidden = FORBIDDEN_FLAGS[head]
+        return true unless forbidden
+
+        tokens.drop(1).none? do |token|
+          forbidden.any? { |flag| token == flag || token.start_with?("#{flag}=") }
+        end
+      end
+
+      # Read-only git: a safe subcommand (no global flags before it — `git -C`
+      # falls to the prompt), never --output (git log/diff/show can write a
+      # file with it), branch/remote in their pure listing forms only.
+      def safe_git?(tokens)
+        sub = tokens[1]
+        return false if sub.nil? || sub.start_with?("-")
+
+        rest = tokens.drop(2)
+        return false if rest.any? { |t| t == "--output" || t.start_with?("--output=") }
+
+        case sub
+        when *GIT_READONLY_SUBCOMMANDS then true
+        when "branch" then rest.all? { |t| GIT_BRANCH_READONLY_FLAGS.include?(t) }
+        when "remote" then rest.empty? || rest == ["-v"] || rest == ["--verbose"]
+        else false
+        end
+      end
+
+      # approvals.readonly_commands entries extend the built-in set: a bare
+      # name ("jq") matches that head, a multi-word entry ("docker ps")
+      # matches those leading tokens exactly.
+      def extra_match?(tokens, extra)
+        Array(extra).any? do |entry|
+          entry_tokens = entry.to_s.strip.split(/\s+/)
+          !entry_tokens.empty? && tokens.first(entry_tokens.length) == entry_tokens
+        end
+      end
+    end
+  end
+end

data/lib/rubino/session/exporter.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Rubino
+  module Session
+    # Serializes one session's transcript to clean markdown — the `/export`
+    # backend. Deliberately minimal: user/assistant turns verbatim, tool
+    # calls and tool results as one-liners, system rows (prompt scaffolding,
+    # compaction summaries) omitted. Reasoning never reaches the message
+    # store, so a transcript export is reasoning-free by construction.
+    class Exporter
+      # Tool-call arguments are context, not payload — clamp the one-liner.
+      ARGS_PREVIEW_CHARS = 120
+
+      def initialize(session, store: Store.new)
+        @session = session
+        @store = store
+      end
+
+      # The full markdown document for the session.
+      def markdown
+        lines = header
+        @store.for_session(@session[:id]).each do |msg|
+          lines.concat(render(msg))
+        end
+        "#{lines.join("\n")}\n"
+      end
+
+      # Writes #markdown to +path+ (default ./rubino-session-<id8>.md in the
+      # current directory) and returns the absolute path written.
+      def write(path = nil)
+        target = File.expand_path(path.to_s.empty? ? default_filename : path.to_s)
+        File.write(target, markdown)
+        target
+      end
+
+      def default_filename
+        "rubino-session-#{@session[:id].to_s[0, 8]}.md"
+      end
+
+      private
+
+      def header
+        meta = ["- session: #{@session[:id]}"]
+        meta << "- title: #{@session[:title]}" if @session[:title]
+        meta << "- model: #{@session[:model]}" if @session[:model]
+        meta << "- exported: #{Time.now.utc.iso8601}"
+        ["# rubino session #{@session[:id].to_s[0, 8]}", "", *meta, ""]
+      end
+
+      def render(msg)
+        case msg.role.to_s
+        when "user" then ["## User", "", msg.content.to_s, ""]
+        when "assistant" then render_assistant(msg)
+        when "tool" then render_tool(msg)
+        else []
+        end
+      end
+
+      # The assistant turn's visible text. The tool-call one-liner is emitted by
+      # #render_tool from the `tool`-role result row (which carries `tool_name` +
+      # `arguments` on BOTH the streaming and non-streaming paths), NOT here from
+      # the assistant row's `tool_calls` metadata — that metadata is absent on the
+      # streaming path (the default; the call is emitted mid-stream), so reading
+      # it left the call one-liner dead in every real export (#216). A pure
+      # tool-call turn has no visible text, so this renders just the heading.
+      def render_assistant(msg)
+        lines = ["## Assistant", ""]
+        text = msg.content.to_s
+        lines.push(text, "") unless text.empty?
+        lines
+      end
+
+      # A `tool`-role row renders its call one-liner (reconstructed from the
+      # row's own `tool_name` + `arguments` metadata) followed by its result
+      # one-liner. The call line is the only place the command/args survive on
+      # the streaming path, where the assistant turn persists without
+      # `tool_calls` (#216).
+      def render_tool(msg)
+        name = msg.tool_name || "tool"
+        args = msg.metadata.is_a?(Hash) ? msg.metadata[:arguments] : nil
+        [
+          "- tool call: `#{name}` #{args_preview(args)}".rstrip, "",
+          "- tool result: `#{name}` (#{msg.content.to_s.length} chars)", ""
+        ]
+      end
+
+      def args_preview(arguments)
+        return "" if arguments.nil? || arguments == {}
+
+        text = arguments.is_a?(String) ? arguments : JSON.generate(arguments)
+        text = "#{text[0, ARGS_PREVIEW_CHARS]}…" if text.length > ARGS_PREVIEW_CHARS
+        "`#{text}`"
+      rescue StandardError
+        ""
+      end
+    end
+  end
+end

data/lib/rubino/session/message.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "json"
+
+module Rubino
+  module Session
+    # Handles message persistence within a session.
+    # Messages include user input, assistant responses, tool calls and results.
+    class Message
+      VALID_ROLES = %w[system user assistant tool].freeze
+
+      attr_reader :id, :session_id, :role, :content, :tool_name,
+                  :tool_call_id, :token_count, :metadata, :created_at
+
+      def initialize(attrs = {})
+        @id = attrs[:id] || SecureRandom.uuid
+        @session_id = attrs[:session_id]
+        @role = attrs[:role]
+        @content = attrs[:content]
+        @tool_name = attrs[:tool_name]
+        @tool_call_id = attrs[:tool_call_id]
+        @token_count = attrs[:token_count] || 0
+        @metadata = attrs[:metadata] || {}
+        @created_at = attrs[:created_at] || Time.now.utc.iso8601
+      end
+
+      # Validates the message attributes
+      def valid?
+        VALID_ROLES.include?(@role) && @session_id
+      end
+
+      # Returns a hash suitable for database insertion
+      def to_row
+        {
+          id: @id,
+          session_id: @session_id,
+          role: @role,
+          content: @content,
+          tool_name: @tool_name,
+          tool_call_id: @tool_call_id,
+          token_count: @token_count,
+          metadata_json: @metadata.empty? ? nil : JSON.generate(@metadata),
+          created_at: @created_at
+        }
+      end
+
+      # Returns a hash for LLM context building. A user message that collapsed a
+      # large paste keeps the compact "[Pasted text #N …]" placeholder in its
+      # stored/displayed content (#213); here we expand each placeholder back to
+      # its full body for the model, so the provider sees everything while the
+      # transcript echo (live AND on resume) stays clean.
+      def to_context
+        msg = { role: @role, content: expand_pastes(@content) }
+        msg[:tool_call_id] = @tool_call_id if @tool_call_id
+        msg[:name] = @tool_name if @tool_name
+        # Surface assistant tool_calls (persisted as metadata) so the adapter
+        # can rebuild the toolUse block expected by strict providers on resume.
+        msg[:tool_calls] = @metadata[:tool_calls] if @metadata.is_a?(Hash) && @metadata[:tool_calls]
+        msg
+      end
+
+      private
+
+      # Substitutes each stored [token, body] paste expansion back into +text+.
+      # The pairs are stored as an array (not a hash) so the placeholder tokens
+      # survive the metadata JSON round-trip without being mangled into symbols.
+      def expand_pastes(text)
+        return text unless text.is_a?(String) && @metadata.is_a?(Hash)
+
+        Array(@metadata[:paste_expansions]).reduce(text) do |acc, (token, body)|
+          token && body ? acc.gsub(token, body) : acc
+        end
+      end
+    end
+  end
+end