protege 0.1.0.alpha.1

data/lib/generators/protege/postfix/templates/deploy/mail/provision.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""Provision the Protege mail accessory's OpenDKIM/Postfix config from a domain manifest.
+
+The Rails app PUSHES the full domain manifest (every EmailDomain + its DKIM key) to this listener
+whenever a domain changes — see Protege::Gateway.push_mail_provisioning. We rewrite the OpenDKIM key
+tables and the Postfix transport/relay_domains from it, then reload. The same apply() runs once at
+container boot from the cached manifest, so a restart self-heals without waiting for a push.
+
+Auth reuses RAILS_INBOUND_EMAIL_PASSWORD (the same shared secret the inbound relay uses). The listener
+binds the internal Kamal network only and is never published to the host — port 25 is the only exposed
+port. This keeps the private keys on the internal hop, same trust boundary as the plaintext SMTP relay.
+"""
+import base64
+import grp
+import hmac
+import json
+import os
+import pwd
+import signal
+import subprocess
+import sys
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+DATA_DIR = "/var/lib/protege-mail"
+KEYS_DIR = os.path.join(DATA_DIR, "keys")
+MANIFEST_PATH = os.path.join(DATA_DIR, "manifest.json")
+KEY_TABLE = "/etc/opendkim/KeyTable"
+SIGNING_TABLE = "/etc/opendkim/SigningTable"
+TRANSPORT = "/etc/postfix/transport"
+OPENDKIM_PID = "/run/opendkim/opendkim.pid"
+HEADER = "# generated at runtime by provision.py — do not edit\n"
+PORT = int(os.environ.get("MAIL_PROVISION_PORT", "8025"))
+
+
+def _opendkim_ids():
+    """The opendkim uid/gid so written keys/tables are readable by the daemon, or (None, None)."""
+    try:
+        return pwd.getpwnam("opendkim").pw_uid, grp.getgrnam("opendkim").gr_gid
+    except KeyError:
+        return None, None
+
+
+def apply(manifest):
+    """Rewrite key files + OpenDKIM/Postfix tables from the manifest, then reload (best-effort)."""
+    domains = manifest.get("domains", [])
+    uid, gid = _opendkim_ids()
+    os.makedirs(KEYS_DIR, exist_ok=True)
+
+    key_lines, signing_lines, transport_lines, relay_domains = [], [], [], []
+    for entry in domains:
+        domain = entry["domain"]
+        selector = entry.get("selector") or "default"
+        pem = entry["private_key_pem"]
+
+        key_dir = os.path.join(KEYS_DIR, domain)
+        os.makedirs(key_dir, exist_ok=True)
+        key_path = os.path.join(key_dir, selector + ".private")
+        with open(key_path, "w") as handle:
+            handle.write(pem if pem.endswith("\n") else pem + "\n")
+        os.chmod(key_path, 0o600)
+        if uid is not None:
+            os.chown(key_path, uid, gid)
+            os.chown(key_dir, uid, gid)
+
+        key_lines.append("%s._domainkey.%s %s:%s:%s" % (selector, domain, domain, selector, key_path))
+        signing_lines.append("*@%s %s._domainkey.%s" % (domain, selector, domain))
+        transport_lines.append("%s actionmailbox:" % domain)
+        relay_domains.append(domain)
+
+    _write(KEY_TABLE, key_lines, uid, gid)
+    _write(SIGNING_TABLE, signing_lines, uid, gid)
+    _write(TRANSPORT, transport_lines, None, None)
+
+    _run(["postmap", TRANSPORT])
+    _run(["postconf", "-e", "relay_domains=" + " ".join(relay_domains)])
+    _reload()
+    _cache(manifest)
+    return len(domains)
+
+
+def _write(path, lines, uid, gid):
+    with open(path, "w") as handle:
+        handle.write(HEADER)
+        for line in lines:
+            handle.write(line + "\n")
+    if uid is not None:
+        try:
+            os.chown(path, uid, gid)
+        except OSError:
+            pass
+
+
+def _run(cmd):
+    """Run a command, swallowing failures — reloads are best-effort (a service may not be up yet)."""
+    try:
+        subprocess.run(cmd, check=True)
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        pass
+
+
+def _reload():
+    _run(["postfix", "reload"])
+    try:
+        with open(OPENDKIM_PID) as handle:
+            os.kill(int(handle.read().strip()), signal.SIGUSR1)
+    except (OSError, ValueError):
+        pass
+
+
+def _cache(manifest):
+    os.makedirs(DATA_DIR, exist_ok=True)
+    with open(MANIFEST_PATH, "w") as handle:
+        json.dump(manifest, handle)
+
+
+def _load_cached():
+    try:
+        with open(MANIFEST_PATH) as handle:
+            return json.load(handle)
+    except (OSError, ValueError):
+        return None
+
+
+class Handler(BaseHTTPRequestHandler):
+    def do_POST(self):
+        if self.path != "/provision":
+            return self._send(404, {"error": "not found"})
+        if not self._authorized():
+            self.send_response(401)
+            self.send_header("WWW-Authenticate", 'Basic realm="protege-mail"')
+            self.end_headers()
+            return
+        length = int(self.headers.get("Content-Length", 0))
+        try:
+            manifest = json.loads(self.rfile.read(length) or b"{}")
+            count = apply(manifest)
+        except (ValueError, KeyError) as error:
+            return self._send(400, {"error": str(error)})
+        self._send(200, {"ok": True, "domains": count})
+
+    def _authorized(self):
+        expected = os.environ.get("RAILS_INBOUND_EMAIL_PASSWORD", "")
+        header = self.headers.get("Authorization", "")
+        if not expected or not header.startswith("Basic "):
+            return False
+        try:
+            user, _, password = base64.b64decode(header[6:]).decode().partition(":")
+        except (ValueError, UnicodeDecodeError):
+            return False
+        return user == "provision" and hmac.compare_digest(password, expected)
+
+    def _send(self, status, body):
+        payload = json.dumps(body).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def log_message(self, *args):
+        pass  # keep the accessory log focused on mail
+
+
+def serve():
+    HTTPServer(("0.0.0.0", PORT), Handler).serve_forever()
+
+
+def main(argv):
+    command = argv[1] if len(argv) > 1 else "serve"
+    if command == "serve":
+        serve()
+    elif command == "apply":
+        manifest = _load_cached()
+        if manifest is not None:
+            apply(manifest)
+    else:
+        sys.stderr.write("usage: provision.py [serve|apply]\n")
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main(sys.argv)

data/lib/generators/protege/postfix/templates/deploy/mail/relay-to-app.sh

@@ -0,0 +1,28 @@
+#!/bin/sh
+# Postfix pipe transport: forward one inbound message to the Rails relay ingress.
+#
+# Postfix feeds the raw RFC822 message on stdin (see the actionmailbox service in master.cf). We POST it
+# verbatim to Action Mailbox's relay endpoint with HTTP Basic auth (user "actionmailbox", password =
+# the ingress password). On any failure we exit EX_TEMPFAIL (75) so Postfix keeps the message queued and
+# retries, rather than bouncing mail the app briefly couldn't accept.
+set -eu
+
+# Postfix's pipe daemon scrubs the environment, so the entrypoint stashed the relay credentials in a
+# file (readable only by this pipe user). Load them here.
+if [ -r /etc/protege-mail/relay.env ]; then
+  . /etc/protege-mail/relay.env
+fi
+
+: "${APP_RELAY_URL:?APP_RELAY_URL not set}"
+: "${RAILS_INBOUND_EMAIL_PASSWORD:?RAILS_INBOUND_EMAIL_PASSWORD not set}"
+
+if curl --fail --silent --show-error \
+        --user "actionmailbox:${RAILS_INBOUND_EMAIL_PASSWORD}" \
+        --header "Content-Type: message/rfc822" \
+        --data-binary @- \
+        "${APP_RELAY_URL}"; then
+  exit 0
+else
+  echo "relay-to-app: POST to ${APP_RELAY_URL} failed; deferring for retry" >&2
+  exit 75 # EX_TEMPFAIL
+fi

data/lib/generators/protege/postfix/templates/github/workflows/build-mail-image.example.yml

@@ -0,0 +1,50 @@
+# Builds the self-hosted mail image (Postfix + OpenDKIM) and pushes it to your registry. Kamal
+# accessories pull a prebuilt image rather than building one, so this runs separately from your
+# deploy: on changes to deploy/mail/**, or on demand. After it publishes, roll it out with
+# `kamal accessory reboot mail`.
+#
+# To use: rename to build-mail-image.yml and adjust the registry/paths for your setup. As written it
+# publishes to GHCR under your org (ghcr.io/<owner>/protege-mail) using the built-in GITHUB_TOKEN.
+name: Build mail image
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'deploy/mail/**'
+      - '.github/workflows/build-mail-image.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: build-mail-image
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: deploy/mail
+          platforms: linux/amd64
+          push: true
+          tags: |
+            ghcr.io/${{ github.repository_owner }}/protege-mail:latest
+            ghcr.io/${{ github.repository_owner }}/protege-mail:${{ github.sha }}

data/lib/generators/protege/provider/provider_generator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'rails/generators/named_base'
+require_relative '../extension_naming'
+
+module Protege
+  module Generators
+    # Scaffolds an inference provider — the adapter between Protege and an LLM backend — into the host
+    # app's providers directory (+config.providers_path+, default +app/providers+). A provider
+    # subclasses +Protege::Provider+, declares its +protege_id+, and implements +generate+ (hash in,
+    # hash out). It is auto-discovered; activate it by pointing +config.provider_id+ at its id and
+    # putting its credentials under that key in +config.providers+.
+    #
+    # The +Provider+ suffix is applied for you, and the +protege_id+ is derived from the name.
+    #
+    # @example
+    #   bin/rails g protege:provider my_llm
+    class ProviderGenerator < Rails::Generators::NamedBase
+      include ExtensionNaming
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Scaffold a Protege::Provider subclass in the configured providers path (default app/providers).'
+
+      # Render the provider scaffold into +config.providers_path+.
+      #
+      # @return [void]
+      def create_provider
+        template 'provider.rb.tt',
+                 File.join(Protege.configuration.providers_path, "#{extension_file_name('Provider')}.rb")
+      end
+
+      private
+
+      # The symbolic +protege_id+ for this provider — the file name with the +provider+ suffix stripped
+      # (e.g. +my_llm_provider+ → +:my_llm+). This is the id the host references from +config.provider_id+.
+      #
+      # @return [String] the snake_cased id
+      def protege_id
+        extension_file_name('Provider').sub(/_provider\z/, '')
+      end
+    end
+  end
+end

data/lib/generators/protege/provider/templates/provider.rb.tt

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# <%= extension_class_name('Provider') %> — an inference provider: the adapter between Protege and an LLM backend.
+#
+# Subclassing +Protege::Provider+ registers it automatically. Activate it by pointing the engine at its
+# id and giving it credentials in the Protege initializer:
+#
+#   config.provider_id = :<%= protege_id %>
+#   config.providers   = { <%= protege_id %>: { api_key: ENV['<%= protege_id.upcase %>_API_KEY'], model: '...' } }
+#
+# The harness drives one method: +#generate+. It takes an OpenAI-compatible request Hash
+# (+{ messages:, tools: }+) and returns a response Hash (+{ content:, tool_calls:, finish_reason: }+),
+# raising a +Protege::Error+ on transport/auth/parse failure. Read this provider's own settings from
+# its config slice via +options+ below. See +Protege::OpenRouterProvider+ for a complete reference
+# implementation (streaming, error mapping, tool-call normalization).
+class <%= extension_class_name('Provider') %> < Protege::Provider
+  protege_id :<%= protege_id %>
+
+  # Run a blocking, non-streaming completion.
+  #
+  # @param request [Hash] the request hash — +:messages+ and +:tools+ in OpenAI chat-completions shape
+  # @return [Hash] the response hash: +{ content:, tool_calls:, finish_reason: }+
+  # @raise [Protege::Error] on a transport, auth, or parse failure
+  def generate(request)
+    # TODO: call your backend with `request` (merge in `model` and `settings`) and map the reply into
+    # the { content:, tool_calls:, finish_reason: } shape Protege expects.
+    raise NotImplementedError, '<%= extension_class_name('Provider') %>#generate is not implemented yet'
+  end
+
+  # Optional: override to stream tokens as they arrive. The default (from +Protege::Provider+) calls
+  # +generate+ and yields its whole text as one chunk, which is fine until you need real streaming.
+  #
+  # @param request [Hash] the request hash (see {#generate})
+  # @yieldparam chunk [Hash] a +{ type: :text, content: String }+ token chunk
+  # @return [Hash] the final assembled response hash
+  # def generate_stream(request, &block)
+  #   super
+  # end
+
+  private
+
+  # This provider's slice of +config.providers+, keyed by its own +protege_id+ (+:<%= protege_id %>+).
+  # Empty when the host hasn't configured it. Read credentials/model/sampling from here — never ENV
+  # directly, so all configuration flows through the initializer.
+  #
+  # @return [Hash] this provider's configured options (or +{}+)
+  def options
+    Protege.configuration.provider_options(self.class.id)
+  end
+end

data/lib/generators/protege/resolver/resolver_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'rails/generators/named_base'
+require_relative '../extension_naming'
+
+module Protege
+  module Generators
+    # Scaffolds a Protege resolver — one link in a persona's context-building chain — into the host
+    # app's resolvers directory (+config.resolvers_path+, default +app/resolvers+). A resolver
+    # subclasses +Protege::Resolver+ and implements +resolve+, contributing zero or more
+    # +Protege::ModelMessage+s to the prompt the harness sends the model.
+    #
+    # Unlike tools, resolvers are NOT auto-discovered: add the class to a persona's chain
+    # (+chain.use MyResolver+) for it to run. The +Resolver+ suffix is applied for you.
+    #
+    # @example
+    #   bin/rails g protege:resolver thread_summary
+    class ResolverGenerator < Rails::Generators::NamedBase
+      include ExtensionNaming
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Scaffold a Protege::Resolver subclass in the configured resolvers path (default app/resolvers).'
+
+      # Render the resolver scaffold into +config.resolvers_path+.
+      #
+      # @return [void]
+      def create_resolver
+        template 'resolver.rb.tt',
+                 File.join(Protege.configuration.resolvers_path, "#{extension_file_name('Resolver')}.rb")
+      end
+    end
+  end
+end

data/lib/generators/protege/resolver/templates/resolver.rb.tt

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# <%= extension_class_name('Resolver') %> — contributes context to the prompt before the model runs.
+#
+# A resolver is one link in a persona's chain. Subclass +Protege::Resolver+, implement +#resolve+, and
+# add it to a chain to activate it (resolvers are NOT auto-discovered):
+#
+#   # in app/personas/your_persona.rb
+#   message_resolvers        { |chain| chain.use <%= extension_class_name('Resolver') %> }  # reply runs
+#   responsibility_resolvers { |chain| chain.use <%= extension_class_name('Resolver') %> }  # scheduled runs
+#
+# +#resolve+ returns one +Protege::ModelMessage+, an Array of them, or +nil+ to contribute nothing.
+# Build messages with the +message+ helper — never construct +ModelMessage+ by hand.
+class <%= extension_class_name('Resolver') %> < Protege::Resolver
+  # Contribute this resolver's slice of context.
+  #
+  # The +context+ tells you which kind of run this is (read it, never mutate it — it is frozen):
+  #   - reply run:     +context.message+ is the inbound +Protege::Message+ (and +context.message.email_thread+)
+  #   - scheduled run: +context.responsibility+ is the +Protege::Responsibility+; +context.message+ is nil
+  # Both always expose +context.persona+, +context.config+, and +context.logger+.
+  #
+  # Pick a +role+ for what you contribute: +:system+ for standing instructions/facts, +:user+ or
+  # +:assistant+ for conversation turns, +:tool+ for a replayed tool result.
+  #
+  # @param context [Protege::Orchestrator::Context] the frozen run context
+  # @return [Protege::ModelMessage, Array<Protege::ModelMessage>, nil] the contribution, or nil for none
+  def resolve(context:)
+    # TODO: build and return your context. Return nil when there is nothing to add.
+    message(role: :system, content: "TODO: context for #{context.persona.name}")
+  end
+end

data/lib/generators/protege/tool/templates/tool.rb.tt

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# <%= extension_class_name('Tool') %> — a capability the agent can call mid-conversation.
+#
+# Subclassing +Protege::Tool+ registers this tool automatically (no wiring): the harness publishes it
+# in the model's tool catalog and routes matching tool calls to +#use+. The tool's id is derived from
+# this class name with the +Tool+ suffix stripped and snake_cased — here +:<%= extension_file_name('Tool').sub(/_tool\z/, '') %>+.
+#
+# Fill in the three things the model relies on:
+#   1. +description+ — WHEN to reach for this tool and WHAT it does, written for the model to read.
+#   2. +input_schema+ — the JSON Schema for the arguments; the model must produce arguments matching it.
+#   3. +#use+ — the behaviour, returning a +Protege::Result+.
+class <%= extension_class_name('Tool') %> < Protege::Tool
+  # Shown to the model as this tool's contract. Be concrete about when it should (and should not) be
+  # used — this is the model's only guidance for choosing it.
+  description <<~DESC.strip
+    TODO: Describe what this tool does and when the agent should call it. Written for the model.
+  DESC
+
+  # The JSON Schema the model's arguments must satisfy. Keys here arrive as symbol keyword arguments to
+  # +#use+. Keep it tight — +additionalProperties: false+ and an explicit +required+ list steer the
+  # model toward valid calls.
+  input_schema(
+    type:                 'object',
+    additionalProperties: false,
+    required:             %w[example],
+    properties:           {
+      example: {
+        type:        'string',
+        description: 'TODO: describe this argument for the model.'
+      }
+    }
+  )
+
+  # Run the tool. Called by the harness with the run +context+ and the model's parsed arguments as
+  # keyword arguments matching {input_schema}.
+  #
+  # Return a +Protege::Result+: +success(**data)+ with any data to hand back to the model, or
+  # +failure(reason:)+ with a short explanation it can act on. A raised error is caught and reported to
+  # the model as a failure, so raise freely for the genuinely exceptional.
+  #
+  # @param context [Protege::Orchestrator::Context] the run context — +context.message+ on a reply run
+  #   (and its +email_thread+), +context.responsibility+ on a scheduled run, plus +persona+/+logger+
+  # @param example [String] the example argument declared in {input_schema} (rename to your own)
+  # @return [Protege::Result] the outcome handed back to the model
+  def use(context:, example:)
+    # TODO: implement. `context` gives you the persona and the current message/thread or responsibility.
+    success(echo: example)
+  end
+end

data/lib/generators/protege/tool/tool_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'rails/generators/named_base'
+require_relative '../extension_naming'
+
+module Protege
+  module Generators
+    # Scaffolds a Protege tool — a capability the agent can invoke mid-conversation — into the host
+    # app's tools directory (+config.tools_path+, default +app/tools+). A tool subclasses
+    # +Protege::Tool+, declares its +description+ and JSON +input_schema+ for the model, and implements
+    # +use+; the harness auto-discovers it (no manual registration) and publishes it in the LLM's tool
+    # catalog.
+    #
+    # The +Tool+ suffix is applied for you, so all of +send_email+, +SendEmail+, and +SendEmailTool+
+    # produce class +SendEmailTool+ in +send_email_tool.rb+.
+    #
+    # @example
+    #   bin/rails g protege:tool send_email
+    class ToolGenerator < Rails::Generators::NamedBase
+      include ExtensionNaming
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Scaffold a Protege::Tool subclass in the configured tools path (default app/tools).'
+
+      # Render the tool scaffold into +config.tools_path+.
+      #
+      # @return [void]
+      def create_tool
+        template 'tool.rb.tt', File.join(Protege.configuration.tools_path, "#{extension_file_name('Tool')}.rb")
+      end
+    end
+  end
+end