protege 0.1.0.alpha.1

data/app/tools/protege/create_file_tool.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Protege
+  # Built-in tool that turns content the agent authored into a stored file it can later attach to an
+  # email. Subclasses +Protege::Tool+, so the harness publishes it in the LLM's tool catalog (id
+  # +:create_file+); when the model calls it, the harness routes the arguments to +#use+.
+  #
+  # The file is written to Active Storage as a standalone +ActiveStorage::Blob+ (no owner record) and
+  # the tool returns its +blob_id+. That id is the currency the +send_email+ tool accepts, so the flow
+  # is: author content here, get a blob id, then reference it from +send_email+'s +attachments+. Keeping
+  # storage and sending as two steps lets the agent create several files, review them via
+  # +read_attachment+, and attach any subset.
+  #
+  # The LLM only ever supplies *text*; the engine never asks it for binary bytes. The +format+ enum is
+  # therefore the whole capability surface — each maps to a content type the authored text is stored
+  # under. A format that needs a real transform (e.g. HTML->PDF) is a later addition; today every
+  # format stores the text as-is.
+  class CreateFileTool < Protege::Tool
+    # Supported formats mapped to the content type the authored text is stored under. The keys are the
+    # +format+ enum; the format name is also the file extension. New text formats are one row here.
+    FORMATS = {
+      csv:  'text/csv',
+      txt:  'text/plain',
+      md:   'text/markdown',
+      html: 'text/html',
+      json: 'application/json',
+      svg:  'image/svg+xml'
+    }.freeze
+
+    description <<~DESC.strip
+      Create a file from content you write, and get back a blob id you can attach to an email.
+
+      Use this when the user wants a document — a CSV of data, an HTML or Markdown report, a JSON
+      export, an SVG chart. Write the full file content yourself in the chosen format; it is stored as
+      a file and you receive its id. To send it, call send_email with that id in attachments (you can
+      create several files and attach any of them). You can also review a file you made with
+      read_attachment before sending.
+
+      Supported formats: csv, txt, md, html, json, svg. Provide the content as text — for csv write the
+      rows, for html/svg write the markup, for json write the JSON.
+    DESC
+
+    input_schema(
+      type:                 'object',
+      additionalProperties: false,
+      required:             %w[format filename content],
+      properties:           {
+        format:   {
+          type:        'string',
+          enum:        FORMATS.keys.map(&:to_s),
+          description: 'The file format. Determines the content type and extension.'
+        },
+        filename: {
+          type:        'string',
+          description: 'The base filename (the correct extension is applied automatically).'
+        },
+        content:  {
+          type:        'string',
+          description: 'The complete file content you authored, as text in the chosen format.'
+        }
+      }
+    )
+
+    # Render the authored content to a stored blob and return its id.
+    #
+    # @param context [Protege::Orchestrator::Context] the per-run context (unused — a blob has no owner)
+    # @param format [String] one of {FORMATS}'s keys
+    # @param filename [String] the base filename; normalized to carry the format's extension
+    # @param content [String] the file content the model authored
+    # @return [Protege::Result] success carrying +blob_id+ and metadata, or a failure (unknown format
+    #   or a size-limit breach)
+    def use(context:, format:, filename:, content:)
+      content_type = FORMATS[format.to_sym]
+      return failure(reason: "unknown format #{format.inspect}") unless content_type
+
+      bytes     = content.to_s.b
+      violation = Protege.configuration.attachment_policy.violation(byte_sizes: [bytes.bytesize])
+      return failure(reason: violation) if violation
+
+      blob = ActiveStorage::Blob.create_and_upload!(
+        io:           StringIO.new(bytes),
+        filename:     with_extension(filename, format),
+        content_type:
+      )
+
+      success(
+        blob_id:      blob.id,
+        filename:     blob.filename.to_s,
+        byte_size:    blob.byte_size,
+        content_type:
+      )
+    end
+
+    private
+
+    # Normalize +filename+ to carry the format's extension, replacing a wrong or missing one.
+    #
+    # @param filename [String] the base filename supplied by the model
+    # @param format [String, Symbol] the chosen format (its name is the extension)
+    # @return [String] the filename ending in +.<format>+
+    def with_extension(filename, format)
+      base = File.basename(filename.to_s.strip)
+      base = base.delete_suffix(File.extname(base)) unless File.extname(base).empty?
+      base = 'file' if base.empty?
+
+      "#{base}.#{format}"
+    end
+  end
+end

data/app/tools/protege/read_attachment_tool.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Protege
+  # Built-in tool that reads a stored file by its blob id. Subclasses +Protege::Tool+, so the harness
+  # publishes it in the LLM's tool catalog (id +:read_attachment+).
+  #
+  # The agent learns a file's blob id from the +ThreadHistoryResolver+/inbound note ("…, id: 123") or
+  # from +create_file+. Resolution is by blob id (see +Protege::StoredFile.find+); persona scoping is
+  # deferred to a later pass (see the blob-currency spec §9), so any known blob id currently resolves.
+  # Behaviour by type:
+  #
+  # - **text-like** (text/*, json, xml, csv) → the text content is returned in the result.
+  # - **image / PDF** → returned as a "review" marker carrying only the blob id (no bytes); the harness
+  #   rebuilds it as a vision part and injects it on the next user turn, because OpenAI-schema tool
+  #   results can't carry images. The model then sees the actual image/PDF.
+  # - **anything else** (video, archives) → a failure; it can't be read.
+  class ReadAttachmentTool < Protege::Tool
+    description <<~DESC.strip
+      Read a file by the id shown in the conversation history (e.g. "id: 123") or returned by
+      create_file.
+
+      Text files (txt, csv, markdown, json, xml) are returned to you as text. Images and PDFs are
+      shown to you directly to view. Other types (such as video or archives) can't be read.
+    DESC
+
+    input_schema(
+      type:                 'object',
+      additionalProperties: false,
+      required:             %w[blob_id],
+      properties:           {
+        blob_id: {
+          type:        'integer',
+          description: 'The id of the file to read, as shown in the conversation history.'
+        }
+      }
+    )
+
+    # Resolve the file by blob id and read it according to its type.
+    #
+    # @param context [Protege::Orchestrator::Context] the per-run context (unused — resolution is by id)
+    # @param blob_id [Integer] the blob id from the conversation history or +create_file+
+    # @return [Protege::Result] text content, a review marker (image/PDF), or a failure
+    def use(context:, blob_id:)
+      file = Protege::StoredFile.find(blob_id)
+      return missing_failure(blob_id) unless file
+
+      if file.text?
+        text_result(file)
+      elsif file.viewable?
+        review_result(file)
+      else
+        unviewable_failure(file)
+      end
+    end
+
+    private
+
+    # Success carrying the file's text content.
+    #
+    # @param file [Protege::StoredFile] the resolved file
+    # @return [Protege::Result] the text result
+    def text_result(file)
+      success(
+        filename:     file.filename,
+        content_type: file.content_type,
+        content:      file.download
+      )
+    end
+
+    # Success marking the file for visual review — only the blob id is carried, never the bytes; the
+    # harness injects the image/PDF as a vision part on the next user turn.
+    #
+    # @param file [Protege::StoredFile] the resolved file
+    # @return [Protege::Result] the review marker
+    def review_result(file)
+      success(
+        blob_id:      file.id,
+        review:       true,
+        filename:     file.filename,
+        content_type: file.content_type,
+        note:         "Showing #{file.filename} below for you to review."
+      )
+    end
+
+    # Failure for a blob id that matches no stored file.
+    #
+    # @param blob_id [Integer] the requested blob id
+    # @return [Protege::Result] the not-found failure
+    def missing_failure(blob_id)
+      failure(reason: "no file ##{blob_id}")
+    end
+
+    # Failure for a file whose type can't be read (e.g. video, archive).
+    #
+    # @param file [Protege::StoredFile] the resolved file
+    # @return [Protege::Result] the unviewable failure
+    def unviewable_failure(file)
+      failure(reason: "attachment #{file.filename} (#{file.content_type}) can't be read")
+    end
+  end
+end

data/app/tools/protege/search_emails_tool.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Protege
+  # Built-in archive-search tool — the way an agent looks back across its own correspondence beyond
+  # the current thread. Subclasses +Protege::Tool+, so the harness publishes it in the LLM's tool
+  # catalog (id +:search_emails+); when the model emits a +search_emails+ call, the harness routes the
+  # arguments to +#use+.
+  #
+  # The search is always scoped to the active persona's own messages (via +Persona#messages+) — an
+  # agent can never read another persona's mail. A single free-text query is matched, case-insensitively,
+  # against both the participants (from/to/cc) and the content (subject/body); results come back newest
+  # first. Each result carries the message's *full* body — a truncated body could cut the very text that
+  # matched, so it is returned whole. The caller may cap the result count with +limit+ (default
+  # {DEFAULT_LIMIT}, hard-capped at {MAX_LIMIT}); the default is small precisely because bodies are full.
+  class SearchEmailsTool < Protege::Tool
+    # Result count when the caller does not specify a +limit+. Kept small because each result carries
+    # the full message body.
+    DEFAULT_LIMIT = 5
+
+    # Absolute ceiling on the result count, regardless of the requested +limit+.
+    MAX_LIMIT = 50
+
+    # Columns scanned by the query: the participant addresses first, then the subject and bodies.
+    SEARCHABLE_COLUMNS = %w[
+      from_address to_addresses cc_addresses subject text_body html_body
+    ].freeze
+
+    description <<~DESC.strip
+      Search your own email archive for past messages — use this to recall earlier conversations that
+      are not part of the thread you are currently replying to. Only your own sent and received mail is
+      searched; you cannot see other agents' mail.
+
+      The query is matched against both participants (from / to / cc addresses) and content (subject and
+      body), so you can search by who was involved ("acme.co", "bob@acme.co") or by what was discussed
+      ("Q3 invoice", "renewal"). Matching messages are returned newest first, each with its full body and
+      a list of any attachments (filename, type, size, and id) — use an id with read_attachment to view
+      one or with send_email to re-attach it.
+
+      Provide a single query string. Optionally set limit to cap the number of results (default 5,
+      maximum 50) — keep it small, since every result includes the whole message body. Narrow the query
+      rather than raising the limit when you get too many hits.
+    DESC
+
+    input_schema(
+      type:                 'object',
+      additionalProperties: false,
+      required:             %w[query],
+      properties:           {
+        query: {
+          type:        'string',
+          description: 'Free-text search matched against participants (from/to/cc) and content ' \
+                       '(subject/body).'
+        },
+        limit: {
+          type:        'integer',
+          description: 'Maximum number of results to return. Defaults to 5; capped at 50.'
+        }
+      }
+    )
+
+    # Search the active persona's archive and return the matching messages as concise summaries.
+    #
+    # @param context [Protege::Orchestrator::Context] exposes the active +persona+
+    # @param query [String] the free-text query supplied by the model
+    # @param limit [Integer, nil] optional result cap (defaults to {DEFAULT_LIMIT}, capped at {MAX_LIMIT})
+    # @return [Protege::Result] success carrying +count+ and the shaped +results+, or a failure when
+    #   the query is blank
+    def use(context:, query:, limit: nil)
+      return failure(reason: 'query cannot be empty') if query.to_s.strip.empty?
+
+      hits = matches(persona: context.persona, query:, limit:)
+
+      success(count: hits.size, results: hits.map { result_hash(_1) })
+    end
+
+    private
+
+    # Build and run the scoped, wildcard-escaped LIKE query, newest first.
+    #
+    # @param persona [Protege::Persona] the persona whose messages are searched
+    # @param query [String] the raw query supplied by the model
+    # @param limit [Integer, nil] the requested cap, clamped into 1..{MAX_LIMIT}
+    # @return [Array<Protege::Message>] the matching messages, newest first
+    def matches(persona:, query:, limit:)
+      count   = (limit || DEFAULT_LIMIT).to_i.clamp(1, MAX_LIMIT)
+      escaped = ActiveRecord::Base.sanitize_sql_like(query.strip.downcase)
+      clause  = SEARCHABLE_COLUMNS.map { "LOWER(#{_1}) LIKE :term" }.join(' OR ')
+
+      persona.messages
+             .with_attached_attachments
+             .where(clause, term: "%#{escaped}%")
+             .order(sent_at: :desc)
+             .limit(count)
+             .to_a
+    end
+
+    # Shape a single message into a result summary. The body is returned in full (never truncated) so
+    # the matched text is always present, and any attachments are listed so the model can pull one into
+    # view with +read_attachment+ or re-send it with +send_email+ by its id.
+    #
+    # @param message [Protege::Message] the matched message
+    # @return [Hash] the summary the model reasons over
+    def result_hash(message)
+      base = {
+        message_id:   message.message_id,
+        thread_id:    message.email_thread.thread_id,
+        direction:    message.direction,
+        from_address: message.from_address,
+        to_addresses: message.to_addresses,
+        subject:      message.subject,
+        sent_at:      message.sent_at.iso8601,
+        body:         message.readable_body
+      }
+
+      summaries = attachment_summaries(message)
+      summaries.empty? ? base : base.merge(attachments: summaries)
+    end
+
+    # One-line summaries (filename, type, human size, blob id) for every attachment on the message,
+    # built from the shared +Protege::StoredFile+ wrapper so search matches the format (and the blob
+    # id) used in thread history and +read_attachment+.
+    #
+    # @param message [Protege::Message] the matched message
+    # @return [Array<String>] the per-attachment summaries (empty when the message has none)
+    def attachment_summaries(message)
+      message.attachments.map { Protege::StoredFile.new(_1.blob).summary }
+    end
+  end
+end

data/app/tools/protege/send_email_tool.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module Protege
+  # Built-in email tool — the way an agent sends mail, in one of two modes. Subclasses
+  # +Protege::Tool+, so the harness publishes it in the LLM's tool catalog (id +:send_email+);
+  # when the model emits a +send_email+ call, the harness routes the arguments to +#use+.
+  #
+  # +From+ is always enforced to the persona's +email_address+ — the agent cannot impersonate another
+  # sender. The +mode+ argument selects behavior:
+  #
+  # * +"reply"+ — continue the current conversation. +Subject+ and threading (+In-Reply-To+ +
+  #   +References+) are derived from the inbound message; the subject is the *thread's* subject, +Re:+
+  #   prefixed, NOT a value the model chooses (Gmail and others require a matching subject to thread, so
+  #   a model-invented subject would split the conversation). The original sender is always a recipient;
+  #   the model may add more via +to+/+cc+/+bcc+.
+  # * +"new"+ — start a fresh conversation. The model supplies +to+ and +subject+ (and optional
+  #   +cc+/+bcc+); no threading headers are set.
+  #
+  # Assembly is delegated to +Protege::Gateway.build_outbound+. The agent may attach files by
+  # referencing blob ids — the ids shown in the conversation history, or returned by +create_file+ —
+  # resolved through +Protege::StoredFile.find+ and checked against the configured
+  # +Gateway::AttachmentPolicy+ limits. (Blob ids currently resolve unscoped; persona scoping is a
+  # deferred pass — see the blob-currency spec §9.)
+  class SendEmailTool < Protege::Tool
+    description <<~DESC.strip
+      YOU MUST USE THIS TOOL FOR EVERY RESPONSE. This is the ONLY way to communicate with the user.
+      They will never receive plain text in your assistant message If you want them to read something,#{' '}
+      you must use this send_email tool.#{' '}
+
+      Set mode:
+
+      - "reply": continue the current conversation. The subject and threading are kept automatically and
+        the original sender is included; add more recipients with to/cc/bcc if you need to.
+      - "new": start a new email. Provide to and subject.
+
+      Always provide body. cc and bcc are optional in both modes. Attach files with attachments — a list
+      of blob ids (e.g. the "id: 123" shown next to a file in the conversation, or the id returned by
+      create_file).
+    DESC
+
+    input_schema(
+      type:                 'object',
+      additionalProperties: false,
+      required:             %w[mode body],
+      properties:           {
+        mode:        {
+          type:        'string',
+          enum:        %w[reply new],
+          description: '"reply" to continue the current conversation, or "new" to start a new email.'
+        },
+        body:        { type: 'string', description: 'Plain text body.' },
+        to:          {
+          type:        'array',
+          items:       { type: 'string' },
+          description: 'Recipients. Required for "new"; for "reply", added beyond the original sender.'
+        },
+        cc:          {
+          type:        'array',
+          items:       { type: 'string' },
+          description: 'Optional carbon-copy recipients.'
+        },
+        bcc:         {
+          type:        'array',
+          items:       { type: 'string' },
+          description: 'Optional blind-carbon-copy recipients.'
+        },
+        subject:     {
+          type:        'string',
+          description: 'Subject for a "new" email. Ignored when replying (the thread subject is kept).'
+        },
+        attachments: {
+          type:        'array',
+          items:       { type: 'integer' },
+          description: 'Optional blob ids (from the conversation history or create_file) to attach.'
+        }
+      }
+    )
+
+    # Build the outbound mail for the requested mode and hand it to the gateway for delivery.
+    #
+    # @param context [Protege::Orchestrator::Context] exposes the inbound +message+, +persona+, and +deliver+
+    # @param mode [String] +"reply"+ or +"new"+
+    # @param body [String] plain-text body supplied by the model
+    # @param to [Array<String>] recipients (required for +"new"+; additions for +"reply"+)
+    # @param cc [Array<String>] carbon-copy recipients
+    # @param bcc [Array<String>] blind-carbon-copy recipients
+    # @param subject [String, nil] subject for a +"new"+ email; ignored when replying
+    # @param attachments [Array<Integer>] blob ids to attach (from history or +create_file+)
+    # @return [Protege::Result] success carrying the sent message's id, or a failure (unknown blob,
+    #   breached limits, nothing to reply to, or a new email missing +to+/+subject+)
+    def use(context:, mode:, body:, to: [], cc: [], bcc: [], subject: nil, attachments: [])
+      files = resolve_attachments(attachments)
+      return files if files.is_a?(Protege::Result) # a failure short-circuits
+
+      mail = build_mail(
+        context:, mode:, to:, cc:, bcc:, subject:, body:, attachments: files.map(&:to_mail_attachment)
+      )
+      return mail if mail.is_a?(Protege::Result) # a validation failure short-circuits
+
+      mail.encoded
+      # Hand the blobs to the gateway so the persisted outbound message attaches them by reference
+      # (no re-upload) — the mail carries the bytes only for transport.
+      context.deliver(mail:, attachments: files.map(&:blob))
+
+      success(message_id: mail.message_id)
+    end
+
+    private
+
+    # Build the outbound mail for the requested mode.
+    #
+    # @param context [Protege::Orchestrator::Context] supplies the inbound message and persona
+    # @param mode [String] +"reply"+ or +"new"+
+    # @param to [Array<String>] recipients
+    # @param cc [Array<String>] carbon-copy recipients
+    # @param bcc [Array<String>] blind-carbon-copy recipients
+    # @param subject [String, nil] subject for a new email
+    # @param body [String] the plain-text body
+    # @param attachments [Array<Gateway::Mail::Attachment>] the resolved mail attachments
+    # @return [Mail::Message, Protege::Result] the assembled mail, or a failure
+    def build_mail(context:, mode:, to:, cc:, bcc:, subject:, body:, attachments:)
+      case mode
+      when 'reply' then reply_mail(context, to:, cc:, bcc:, body:, attachments:)
+      when 'new'   then new_thread_mail(context.persona, to:, cc:, bcc:, subject:, body:, attachments:)
+      else              failure(reason: %(unknown mode #{mode.inspect}; use "reply" or "new"))
+      end
+    end
+
+    # Construct a threaded reply: subject and threading from the inbound message, the original sender
+    # plus any added recipients.
+    #
+    # @param context [Protege::Orchestrator::Context] supplies the inbound message and persona
+    # @param to [Array<String>] recipients to add beyond the original sender
+    # @param cc [Array<String>] carbon-copy recipients
+    # @param bcc [Array<String>] blind-carbon-copy recipients
+    # @param body [String] the plain-text body
+    # @param attachments [Array<Gateway::Mail::Attachment>] the resolved mail attachments
+    # @return [Mail::Message, Protege::Result] the assembled reply, or a failure when there is no inbound
+    def reply_mail(context, to:, cc:, bcc:, body:, attachments:)
+      inbound = context.message
+      return failure(reason: 'there is no message to reply to; send a "new" email instead') unless inbound
+
+      Protege::Gateway.build_outbound(
+        from:        context.persona.email_address,
+        to:          ([inbound.from_address] + addresses(to)).uniq,
+        cc:          addresses(cc),
+        bcc:         addresses(bcc),
+        subject:     ensure_re_prefix(inbound.subject),
+        body:,
+        in_reply_to: inbound.message_id,
+        references:  build_references(inbound),
+        attachments:
+      )
+    end
+
+    # Construct a new-thread email: the model supplies the recipients and subject; no threading headers.
+    #
+    # @param persona [Protege::Persona] the sending persona (enforced From)
+    # @param to [Array<String>] recipients (at least one required)
+    # @param cc [Array<String>] carbon-copy recipients
+    # @param bcc [Array<String>] blind-carbon-copy recipients
+    # @param subject [String, nil] the subject (required)
+    # @param body [String] the plain-text body
+    # @param attachments [Array<Gateway::Mail::Attachment>] the resolved mail attachments
+    # @return [Mail::Message, Protege::Result] the assembled mail, or a failure when +to+/+subject+ is missing
+    def new_thread_mail(persona, to:, cc:, bcc:, subject:, body:, attachments:)
+      recipients = addresses(to)
+      return failure(reason: 'a new email needs at least one "to" recipient') if recipients.empty?
+      return failure(reason: 'a new email needs a subject')                   if subject.to_s.strip.empty?
+
+      Protege::Gateway.build_outbound(
+        from:        persona.email_address,
+        to:          recipients,
+        cc:          addresses(cc),
+        bcc:         addresses(bcc),
+        subject:,
+        body:,
+        attachments:
+      )
+    end
+
+    # Normalize a recipients argument to a clean array of address strings (blank entries dropped).
+    #
+    # @param value [String, Array<String>, nil] the raw recipients
+    # @return [Array<String>] the cleaned addresses
+    def addresses(value)
+      Array(value).map { |address| address.to_s.strip }.reject(&:empty?)
+    end
+
+    # Resolve blob ids to the stored files they name, limit-checked.
+    #
+    # @param ids [Array<Integer>] the requested blob ids
+    # @return [Array<Protege::StoredFile>, Protege::Result] the resolved files, or a failure +Result+
+    #   when a blob id is unknown or the selection breaches the limits
+    def resolve_attachments(ids)
+      resolved = Array(ids).map { |id| [id, Protege::StoredFile.find(id)] }
+
+      missing_id = first_missing_id(resolved)
+      return failure(reason: "no file ##{missing_id}") if missing_id
+
+      files     = resolved.map(&:last)
+      violation = limit_violation(files)
+      return failure(reason: violation) if violation
+
+      files
+    end
+
+    # The first requested blob id that resolved to no file, or +nil+ when all were found.
+    #
+    # @param resolved [Array<Array(Integer, Protege::StoredFile, nil)>] id → file pairs
+    # @return [Integer, nil] the missing id, or nil
+    def first_missing_id(resolved)
+      resolved.find { |_id, file| file.nil? }&.first
+    end
+
+    # The configured attachment-limit breach for the selected files, or +nil+ when within limits.
+    #
+    # @param files [Array<Protege::StoredFile>] the resolved files
+    # @return [String, nil] the limit-breach reason, or nil
+    def limit_violation(files)
+      Protege.configuration.attachment_policy.violation(byte_sizes: files.map(&:byte_size))
+    end
+
+    # Assemble the +References+ chain, extending the inbound chain with the inbound's own id.
+    #
+    # @param inbound [Protege::Message] the message being replied to
+    # @return [Array<String>] the de-duplicated references chain
+    def build_references(inbound)
+      (inbound.references_header.to_s.split + [inbound.message_id]).compact.uniq
+    end
+
+    # Ensure the subject carries a single +Re:+ prefix.
+    #
+    # @param subject [String] the raw subject line
+    # @return [String] the subject, prefixed with +Re:+ unless it already starts with one
+    def ensure_re_prefix(subject)
+      subject.to_s.strip.match?(/\Are:/i) ? subject : "Re: #{subject}"
+    end
+  end
+end