brainiac-zoho 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 386e959b01ecbdba6859b7256d0af025b4f76efe95c77e497ff78a761ee5fd5e
+  data.tar.gz: e035b1208494431bf24a56891fc998000567e4c49bae08edbe1b24b4145d816a
+SHA512:
+  metadata.gz: 2bf6504d360b62f1626d6fd2db180be29fd24e2efa16a47e1fa04a7e9731af005bd223e61a46eeff4eab9c36489477435debcd0b79e31ab64c8b642297cef8d7
+  data.tar.gz: ebc6c1dd39d5d79601da0a58ae9b07612159cbbb49a281a7b0276be6cf2930bdf0ebfb8fd33db1d970f5ca594336e6626754203fb2bcad27ef123642e5feddf0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andy Davis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,86 @@
+# brainiac-zoho
+
+Zoho Mail webhook plugin for [Brainiac](https://github.com/stowzilla/brainiac) — the multi-agent orchestration layer.
+
+## What It Does
+
+- **Email Notifications** — rule-based matching of incoming emails, notifications to Discord
+- **Email Triage** — AI agent dispatched to decide if support emails need a card
+- **OAuth Flow** — browser-based Zoho OAuth for API access (content fetching)
+- **Fallback Rules** — catches unmatched emails so nothing slips through
+
+## Installation
+
+```bash
+brainiac install zoho
+brainiac restart
+```
+
+## Configuration
+
+Config lives at `~/.brainiac/zoho.json`:
+
+```json
+{
+  "hook_secret": null,
+  "default_discord_channel_id": "YOUR_CHANNEL_ID",
+  "notify_as": "merlin",
+  "rules": [
+    {
+      "label": "Item Sold",
+      "enabled": true,
+      "subject_contains": "sold",
+      "emoji": "💰"
+    }
+  ],
+  "fallback": {
+    "enabled": true,
+    "label": "Unmatched Email",
+    "emoji": "📬"
+  }
+}
+```
+
+The `hook_secret` is auto-captured from Zoho's initial handshake — no manual configuration needed.
+
+### Zoho Webhook Setup
+
+1. Go to Zoho Mail → Settings → Developer Space → Outgoing Webhooks
+2. Add webhook URL: `https://your-ngrok.ngrok-free.app/zoho`
+3. On first trigger, Zoho sends the signing secret automatically
+
+### Zoho Mail API (Optional)
+
+For fetching full email content (webhook payloads only include summaries):
+
+1. Add `api` section to `zoho.json` with `client_id` and `client_secret`
+2. Visit `http://localhost:4567/zoho/auth` to complete OAuth
+3. The `refresh_token` and `account_id` are saved automatically
+
+## CLI
+
+```bash
+brainiac zoho setup     # Create config file from template
+brainiac zoho config    # Show current configuration
+brainiac zoho auth      # Instructions for OAuth setup
+```
+
+## Hooks Emitted
+
+| Hook | When | Payload |
+|------|------|---------|
+| `:create_work_item` | Triage agent decides to create card | board_id, title, description, tags, assign_to |
+
+## Development
+
+```bash
+git clone https://github.com/stowzilla/brainiac-zoho.git
+cd brainiac-zoho
+bundle install
+bundle exec rake test
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lib/brainiac/plugins/zoho/cli.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Zoho
+      module Cli
+        class << self
+          def run(args)
+            command = args.shift
+            case command
+            when "setup" then cmd_setup
+            when "config" then cmd_config
+            when "auth" then cmd_auth
+            else print_help
+            end
+          end
+
+          private
+
+          def cmd_setup
+            brainiac_dir = ENV.fetch("BRAINIAC_DIR", File.join(Dir.home, ".brainiac"))
+            config_file = File.join(brainiac_dir, "zoho.json")
+
+            if File.exist?(config_file)
+              puts "Zoho config already exists at #{config_file}"
+              return
+            end
+
+            template = File.expand_path("../../../../templates/zoho.json.example", __dir__)
+            if File.exist?(template)
+              FileUtils.cp(template, config_file)
+              puts "Created #{config_file} from template"
+            else
+              puts "Template not found — creating minimal config"
+              default_config = { "hook_secret" => nil, "default_discord_channel_id" => "", "rules" => [], "fallback" => { "enabled" => true } }
+              File.write(config_file, JSON.pretty_generate(default_config))
+              puts "Created #{config_file}"
+            end
+
+            puts "Edit the file to configure notification rules."
+          end
+
+          def cmd_config
+            brainiac_dir = ENV.fetch("BRAINIAC_DIR", File.join(Dir.home, ".brainiac"))
+            config_file = File.join(brainiac_dir, "zoho.json")
+
+            unless File.exist?(config_file)
+              puts "No Zoho config found. Run: brainiac zoho setup"
+              return
+            end
+
+            config = JSON.parse(File.read(config_file))
+            rules = config["rules"] || []
+            puts "Zoho Configuration:"
+            puts "  Config file: #{config_file}"
+            puts "  Hook secret: #{config["hook_secret"] ? "captured" : "(pending — waiting for first webhook)"}"
+            puts "  Default channel: #{config["default_discord_channel_id"] || "(not set)"}"
+            puts "  Notify as: #{config["notify_as"] || "(default)"}"
+            puts "  Rules: #{rules.size} configured"
+            rules.each { |r| puts "    - #{r["label"]} (#{r["enabled"] == false ? "disabled" : "enabled"})" }
+            puts "  API configured: #{config.dig("api", "refresh_token") ? "yes" : "no"}"
+          end
+
+          def cmd_auth
+            puts "Visit http://localhost:4567/zoho/auth in your browser to start OAuth flow."
+            puts "Make sure brainiac server is running and zoho.json has api.client_id + api.client_secret."
+          end
+
+          def print_help
+            puts "Usage: brainiac zoho <command>"
+            puts ""
+            puts "Commands:"
+            puts "  setup     Create Zoho config file (~/.brainiac/zoho.json)"
+            puts "  config    Show current Zoho configuration"
+            puts "  auth      Instructions for OAuth setup"
+          end
+        end
+      end
+
+      # Plugin CLI entry points
+      def self.cli(args)
+        Cli.run(args)
+      end
+
+      def self.completions
+        %w[setup config auth]
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/zoho/config.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Zoho
+      module Config
+        CONFIG_FILE = File.join(ENV.fetch("BRAINIAC_DIR", File.join(Dir.home, ".brainiac")), "zoho.json")
+
+        @config = {}
+        @last_mtime = nil
+
+        class << self
+          attr_reader :config
+
+          def load!
+            @config = load_config
+            @last_mtime = File.exist?(CONFIG_FILE) ? File.mtime(CONFIG_FILE) : nil
+          end
+
+          def reload!
+            return unless file_changed?
+
+            @config = load_config
+            @last_mtime = File.exist?(CONFIG_FILE) ? File.mtime(CONFIG_FILE) : nil
+            LOG.info "[Zoho] Reloaded configuration"
+          end
+
+          def hook_secret
+            @config["hook_secret"]
+          end
+
+          def save_hook_secret(secret)
+            @config["hook_secret"] = secret
+            File.write(CONFIG_FILE, JSON.pretty_generate(@config))
+            LOG.info "[Zoho] Saved hook_secret to #{CONFIG_FILE}"
+          end
+
+          def default_notify_target
+            @config["default_notify_target"] || @config["default_discord_channel_id"]
+          end
+
+          def notify_channel
+            @config["notify_channel"] || "discord"
+          end
+
+          def notify_as
+            @config["notify_as"]
+          end
+
+          def rules
+            @config["rules"] || []
+          end
+
+          def fallback
+            @config["fallback"]
+          end
+
+          def triage_board_id
+            @config["triage_board_id"]
+          end
+
+          def triage_project_tags
+            tags = @config["triage_project_tags"]
+            return "Use your best judgement to identify the relevant project." unless tags&.any?
+
+            tags.map { |t| "  - `#{t["tag"]}` — #{t["description"]}" }.join("\n")
+          end
+
+          def triage_agent_assignment
+            rules = @config["triage_agent_assignment"]
+            return "Assign to the default agent." unless rules&.any?
+
+            rules.map { |r| "  - #{r}" }.join("\n")
+          end
+
+          def api_section
+            @config["api"] || {}
+          end
+
+          def api_configured?
+            api = api_section
+            api["client_id"] && api["client_secret"] && api["refresh_token"] && api["account_id"]
+          end
+
+          def save_config!
+            File.write(CONFIG_FILE, JSON.pretty_generate(@config))
+          end
+
+          private
+
+          def load_config
+            return {} unless File.exist?(CONFIG_FILE)
+
+            JSON.parse(File.read(CONFIG_FILE))
+          rescue JSON::ParserError => e
+            LOG.error "[Zoho] Failed to parse config: #{e.message}"
+            {}
+          end
+
+          def file_changed?
+            return false unless File.exist?(CONFIG_FILE)
+
+            current_mtime = File.mtime(CONFIG_FILE)
+            return false if @last_mtime && current_mtime == @last_mtime
+
+            @last_mtime = current_mtime
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/zoho/handler.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Zoho
+      module Handler
+        class << self
+          def handle_webhook(email)
+            LOG.info "[Zoho] Received email: subject=#{email["subject"]}, from=#{email["fromAddress"]}, to=#{email["toAddress"]}"
+
+            dump_payload(email)
+            Config.reload!
+
+            rule = match_rule(email)
+            if rule
+              LOG.info "[Zoho] Matched rule: #{rule["label"]}"
+              if rule["dispatch_agent"]
+                Triage.dispatch(email, rule)
+                [200, { status: "triage_dispatched", rule: rule["label"], agent: rule["dispatch_agent"] }.to_json]
+              else
+                notify_match(email, rule)
+                [200, { status: "matched", rule: rule["label"] }.to_json]
+              end
+            else
+              LOG.info "[Zoho] No rules matched"
+              [200, { status: "no_match" }.to_json]
+            end
+          end
+
+          def match_rule(email)
+            rules = Config.rules
+            matched = rules.find { |rule| rule_matches?(rule, email) }
+            return matched if matched
+
+            fallback = fallback_rule
+            return nil if fallback && email_excluded?(email, Config.fallback&.dig("exclude_words"))
+
+            fallback
+          end
+
+          def rule_matches?(rule, email)
+            return false if rule["enabled"] == false
+
+            %w[from_contains to_contains subject_contains].each do |field|
+              pattern = rule[field]
+              next if pattern.nil? || pattern.empty?
+
+              email_field = case field
+                            when "from_contains" then email["fromAddress"]
+                            when "to_contains" then email["toAddress"]
+                            when "subject_contains" then email["subject"]
+                            end
+              return false unless email_field.to_s.downcase.include?(pattern.downcase)
+            end
+
+            if rule["body_contains"] && !rule["body_contains"].empty?
+              body = "#{email["summary"]}#{email["html"]}"
+              return false unless body.downcase.include?(rule["body_contains"].downcase)
+            end
+
+            !email_excluded?(email, rule["exclude_words"])
+          end
+
+          def email_excluded?(email, exclude_words)
+            return false if exclude_words.nil? || exclude_words.empty?
+
+            searchable = [email["subject"], email["fromAddress"], email["toAddress"],
+                          email["summary"], email["html"]].join(" ").downcase
+            Array(exclude_words).any? { |word| searchable.include?(word.downcase) }
+          end
+
+          def notify_match(email, rule)
+            target = rule["notify_target"] || rule["discord_channel_id"] || Config.default_notify_target
+            channel = rule["notify_channel"] || Config.notify_channel
+
+            unless target
+              LOG.warn "[Zoho] No notify_target configured for rule '#{rule["label"]}' and no default set"
+              return
+            end
+
+            message = format_notification(email, rule)
+            agent = rule["notify_as"] || Config.notify_as
+
+            LOG.info "[Zoho] Sending notification via #{channel} to #{target}"
+            send_notification(:zoho_email, message, channel: channel, target: target, agent: agent)
+          end
+
+          def format_notification(email, rule)
+            label = rule["label"] || "Zoho Mail"
+            emoji = rule["emoji"] || "📧"
+            parts = ["#{emoji} **#{label}**"]
+            parts << "**Subject:** #{email["subject"]}" if email["subject"]
+            parts << "**From:** #{email["fromAddress"]}" if email["fromAddress"]
+            parts << "**To:** #{email["toAddress"]}" if email["toAddress"]
+
+            body_text = extract_body_text(email, rule)
+            parts << "```\n#{body_text}\n```" if body_text
+
+            parts.join("\n")
+          end
+
+          private
+
+          def fallback_rule
+            fallback = Config.fallback
+            return nil unless fallback && fallback["enabled"] != false
+
+            { "label" => fallback["label"] || "Unmatched Email",
+              "emoji" => fallback["emoji"] || "📬",
+              "discord_channel_id" => fallback["discord_channel_id"],
+              "notify_as" => fallback["notify_as"] }
+          end
+
+          def extract_body_text(email, rule)
+            body_text = email["summary"].to_s.strip
+            if body_text.empty?
+              raw_html = (email["html"] || email["content"] || email["body"] || "").to_s
+              body_text = raw_html.gsub(/<[^>]+>/, " ").gsub(/&nbsp;/i, " ").gsub(/\s+/, " ").strip
+            end
+
+            body_text = MailApi.fetch_email_content(email["messageId"]).to_s if body_text.empty? && rule["show_body"] && email["messageId"]
+
+            return nil if body_text.empty?
+
+            max_len = rule["show_body"] ? 1800 : 500
+            body_text = "#{body_text[0..max_len]}..." if body_text.length > max_len
+            body_text
+          end
+
+          def dump_payload(email)
+            zoho_debug_dir = File.join(ENV.fetch("BRAINIAC_DIR", File.join(Dir.home, ".brainiac")), "tmp", "zoho", "payloads")
+            FileUtils.mkdir_p(zoho_debug_dir)
+            File.write(File.join(zoho_debug_dir, "#{Time.now.strftime("%Y%m%d-%H%M%S")}.json"), JSON.pretty_generate(email))
+          rescue StandardError => e
+            LOG.warn "[Zoho] Could not dump payload: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/zoho/mail_api.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module Brainiac
+  module Plugins
+    module Zoho
+      module MailApi
+        ZOHO_TOKEN_URL = "https://accounts.zoho.com/oauth/v2/token"
+        ZOHO_MAIL_API_BASE = "https://mail.zoho.com/api/accounts"
+
+        @access_token = nil
+        @token_expires_at = Time.at(0)
+
+        class << self
+          def configured?
+            Config.api_configured?
+          end
+
+          def refresh_access_token!
+            api = Config.api_section
+            uri = URI(ZOHO_TOKEN_URL)
+            res = Net::HTTP.post_form(uri, {
+                                        "grant_type" => "refresh_token",
+                                        "client_id" => api["client_id"],
+                                        "client_secret" => api["client_secret"],
+                                        "refresh_token" => api["refresh_token"]
+                                      })
+
+            data = JSON.parse(res.body)
+            if data["access_token"]
+              @access_token = data["access_token"]
+              @token_expires_at = Time.now + 3300
+              LOG.info "[Zoho:API] Refreshed access token"
+              @access_token
+            else
+              LOG.error "[Zoho:API] Token refresh failed: #{data["error"]}"
+              nil
+            end
+          rescue StandardError => e
+            LOG.error "[Zoho:API] Token refresh error: #{e.message}"
+            nil
+          end
+
+          def access_token
+            return @access_token if @access_token && Time.now < @token_expires_at
+
+            refresh_access_token!
+          end
+
+          # Store token obtained during OAuth callback
+          def store_token(token)
+            @access_token = token
+            @token_expires_at = Time.now + 3300
+          end
+
+          def fetch_email_content(message_id)
+            return nil unless configured?
+
+            token = access_token
+            return nil unless token
+
+            account_id = Config.api_section["account_id"]
+            uri = URI("#{ZOHO_MAIL_API_BASE}/#{account_id}/messages/#{message_id}/originalmessage")
+
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = true
+            req = Net::HTTP::Get.new(uri)
+            req["Authorization"] = "Zoho-oauthtoken #{token}"
+            req["Accept"] = "application/json"
+
+            res = http.request(req)
+            data = JSON.parse(res.body)
+
+            if data.dig("status", "code") == 200
+              raw_mime = data.dig("data", "content").to_s
+              text = extract_text_from_mime(raw_mime)
+              LOG.info "[Zoho:API] Fetched content for message #{message_id} (#{text.length} chars)"
+              text
+            else
+              LOG.warn "[Zoho:API] Failed to fetch content: #{data.dig("status", "description")}"
+              nil
+            end
+          rescue StandardError => e
+            LOG.error "[Zoho:API] Error fetching content: #{e.message}"
+            nil
+          end
+
+          private
+
+          def extract_text_from_mime(mime)
+            if mime =~ %r{Content-Type: text/plain[^\r\n]*\r?\n(?:Content-Transfer-Encoding:[^\r\n]*\r?\n)?(?:\r?\n)(.*?)(?:\r?\n------=_Part|\z)}mi
+              return Regexp.last_match(1).gsub("\r\n", "\n").strip
+            end
+
+            if mime =~ %r{Content-Type: text/html[^\r\n]*\r?\n(?:Content-Transfer-Encoding:[^\r\n]*\r?\n)?(?:\r?\n)(.*?)(?:\r?\n------=_Part|\z)}mi
+              html = Regexp.last_match(1).gsub("\r\n", "\n")
+              return html.gsub(/<[^>]+>/, " ").gsub(/&nbsp;/i, " ").gsub(/&amp;/i, "&")
+                         .gsub(/&lt;/i, "<").gsub(/&gt;/i, ">").gsub(/\s+/, " ").strip
+            end
+
+            mime.gsub(/<[^>]+>/, " ").gsub(/\s+/, " ").strip
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/zoho/metadata.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Lightweight metadata for brainiac-zoho.
+# Loaded by `brainiac help` without pulling in the full plugin runtime.
+
+require_relative "version"
+
+module Brainiac
+  module Plugins
+    module Zoho
+      # Returns true if Zoho config file exists.
+      def self.configured?
+        config_file = File.join(ENV.fetch("BRAINIAC_DIR", File.join(Dir.home, ".brainiac")), "zoho.json")
+        File.exist?(config_file)
+      rescue StandardError
+        false
+      end
+
+      # Help text shown in `brainiac help` when the plugin is installed.
+      def self.help_text
+        "    brainiac zoho <command>       Manage Zoho Mail webhooks (setup, config, auth)"
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/zoho/triage.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Zoho
+      module Triage
+        PROMPT_TEMPLATE = <<~PROMPT
+          You are triaging a support email. Decide whether this email needs a card or not.
+
+          ## Email
+          **From:** {{FROM}}
+          **To:** {{TO}}
+          **Subject:** {{SUBJECT}}
+          **Body:**
+          ```
+          {{BODY}}
+          ```
+
+          ## Decision Criteria
+          **Needs a card** (something is broken, a bug report, a feature request, a workflow issue):
+          - Create a card with a clear title summarizing the issue
+          - Tag with `support` plus a project tag if you can identify the relevant project
+          - Assign to the appropriate agent
+
+          **Does NOT need a card** (account questions, password resets, general inquiries, spam, marketing):
+          - Just explain why briefly
+
+          **Borderline** (you're not sure):
+          - Mark as borderline and explain why — a human will decide
+
+          ## Project Tags (use the tag name, not the ID)
+          {{PROJECT_TAGS}}
+
+          ## Agent Assignment
+          {{AGENT_ASSIGNMENT}}
+
+          ## Response Format
+          Write ONLY valid JSON to stdout (no markdown, no explanation outside the JSON):
+
+          For "needs a card":
+          ```json
+          {
+            "decision": "create_card",
+            "title": "Brief descriptive title for the card",
+            "description": "HTML description with relevant details from the email",
+            "project_tag": "project-tag-name or null",
+            "assign_to": "agent-name from the assignment rules above"
+          }
+          ```
+
+          For "does not need a card":
+          ```json
+          {
+            "decision": "skip",
+            "reason": "Brief explanation of why no card is needed"
+          }
+          ```
+
+          For "borderline":
+          ```json
+          {
+            "decision": "borderline",
+            "reason": "Why you're unsure — what makes this ambiguous"
+          }
+          ```
+        PROMPT
+
+        class << self
+          def dispatch(email, rule)
+            agent_name = rule["dispatch_agent"]
+            timestamp = Time.now.strftime("%Y%m%d-%H%M%S")
+            triage_dir = File.join(ENV.fetch("BRAINIAC_DIR", File.join(Dir.home, ".brainiac")), "tmp", "zoho", "triage")
+            FileUtils.mkdir_p(triage_dir)
+
+            response_file = File.join(triage_dir, "triage-#{timestamp}.json")
+            log_file = File.join(triage_dir, "triage-#{timestamp}.log")
+            prompt_file = write_prompt(email, response_file, timestamp, triage_dir)
+
+            agent_key = agent_name.downcase.gsub(/[^a-z0-9-]/, "-")
+            project_config = default_project_config
+            resolved = resolve_project_cli_config(project_config || {})
+
+            cmd = [resolved["agent_cli"]]
+            cmd.push("--agent", agent_key)
+            cmd.concat(resolved["agent_cli_args"].split)
+
+            spawn_env = {}
+            agent_env = agent_env_for(agent_name)
+            spawn_env.merge!(agent_env) unless agent_env.empty?
+
+            work_dir = project_config ? project_config["repo_path"] : Dir.pwd
+
+            LOG.info "[Zoho:Triage] Dispatching #{agent_name} for: #{email["subject"]}"
+            LOG.info "[Zoho:Triage] Command: #{cmd.join(" ")}"
+
+            pid = spawn(spawn_env, *cmd,
+                        chdir: work_dir, in: prompt_file,
+                        out: [log_file, "w"], err: %i[child out])
+
+            monitor(pid, response_file, log_file, prompt_file, email, rule)
+            pid
+          end
+
+          private
+
+          def default_project_config
+            key = default_project_key
+            key ? PROJECTS[key] : PROJECTS.values.first
+          end
+
+          def write_prompt(email, response_file, timestamp, triage_dir)
+            body = (email["summary"] || email["html"] || "").to_s.gsub(/\s+/, " ").strip
+            body = body[0..2000] if body.length > 2000
+
+            prompt = PROMPT_TEMPLATE
+                     .gsub("{{FROM}}", email["fromAddress"].to_s)
+                     .gsub("{{TO}}", email["toAddress"].to_s)
+                     .gsub("{{SUBJECT}}", email["subject"].to_s)
+                     .gsub("{{BODY}}", body)
+                     .gsub("{{PROJECT_TAGS}}", Config.triage_project_tags)
+                     .gsub("{{AGENT_ASSIGNMENT}}", Config.triage_agent_assignment)
+            prompt += "\n\nWrite your JSON response to: #{response_file}\n"
+
+            prompt_file = File.join(triage_dir, "triage-prompt-#{timestamp}.md")
+            File.write(prompt_file, prompt)
+            prompt_file
+          end
+
+          def monitor(pid, response_file, log_file, prompt_file, email, rule)
+            Thread.new do
+              Process.wait(pid)
+              LOG.info "[Zoho:Triage] Agent finished (exit: #{$CHILD_STATUS.exitstatus})"
+
+              decision = read_response(response_file, log_file)
+              if decision
+                execute_decision(decision, email, rule)
+              else
+                LOG.warn "[Zoho:Triage] No valid decision from agent — falling back to notification"
+                Handler.notify_match(email, rule)
+              end
+
+              Thread.new do
+                sleep 300
+                FileUtils.rm_f(prompt_file)
+              end
+            end
+          end
+
+          def read_response(response_file, log_file)
+            if File.exist?(response_file) && !File.empty?(response_file)
+              content = File.read(response_file).strip
+              return parse_json(content)
+            end
+
+            if File.exist?(log_file)
+              log_content = File.read(log_file)
+              if (match = log_content.match(/\{[^{}]*"decision"\s*:\s*"[^"]+?"[^{}]*\}/m))
+                return parse_json(match[0])
+              end
+            end
+
+            nil
+          end
+
+          def parse_json(content)
+            content = content.gsub(/```json\s*/, "").gsub(/```\s*/, "").strip
+            JSON.parse(content)
+          rescue JSON::ParserError => e
+            LOG.warn "[Zoho:Triage] Failed to parse response JSON: #{e.message}"
+            nil
+          end
+
+          def execute_decision(decision, email, rule)
+            channel_id = rule["notify_target"] || rule["discord_channel_id"] || Config.default_notify_target
+            notify_channel = rule["notify_channel"] || Config.notify_channel
+            bot_name = rule["notify_as"] || Config.notify_as
+
+            case decision["decision"]
+            when "create_card"
+              create_card(decision, email, channel_id, notify_channel, bot_name)
+            when "skip"
+              msg = "📧 **Support Email — No Card Needed**\n"
+              msg += "**Subject:** #{email["subject"]}\n"
+              msg += "**From:** #{email["fromAddress"]}\n"
+              msg += "**Reason:** #{decision["reason"]}"
+              send_notification(:zoho_triage, msg, channel: notify_channel, target: channel_id, agent: bot_name)
+              LOG.info "[Zoho:Triage] Skipped card: #{decision["reason"]}"
+            when "borderline"
+              msg = "⚠️ **Support Email — Needs Human Decision**\n"
+              msg += "**Subject:** #{email["subject"]}\n"
+              msg += "**From:** #{email["fromAddress"]}\n"
+              msg += "**Why borderline:** #{decision["reason"]}\n"
+              summary = (email["summary"] || "").to_s[0..300]
+              msg += "```\n#{summary}\n```" unless summary.empty?
+              send_notification(:zoho_triage, msg, channel: notify_channel, target: channel_id, agent: bot_name)
+              LOG.info "[Zoho:Triage] Borderline — posted for human decision"
+            else
+              LOG.warn "[Zoho:Triage] Unknown decision: #{decision["decision"]}"
+              Handler.notify_match(email, rule)
+            end
+          end
+
+          def create_card(decision, email, channel_id, notify_channel, bot_name)
+            board_id = Config.triage_board_id
+            unless board_id
+              LOG.error "[Zoho:Triage] No triage_board_id configured in zoho.json"
+              return
+            end
+
+            title = decision["title"] || email["subject"]
+            description = decision["description"] || "<p>Support email from #{email["fromAddress"]}: #{email["subject"]}</p>"
+            tags = ["support"]
+            tags << decision["project_tag"] if decision["project_tag"]
+
+            results = Brainiac.emit(:create_work_item,
+                                    board_id: board_id, title: title,
+                                    description: description, tags: tags,
+                                    assign_to: decision["assign_to"])
+
+            card_info = results.compact.first
+            if card_info
+              card_number = card_info[:number]
+              card_url = card_info[:url]
+              LOG.info "[Zoho:Triage] Created card ##{card_number}: #{title}"
+
+              msg = "🎫 **Support Card Created: [##{card_number}](#{card_url})**\n"
+              msg += "**Title:** #{title}\n"
+              msg += "**Assigned to:** #{decision["assign_to"] || "unassigned"}\n"
+              msg += "**Tags:** #{tags.join(", ")}\n"
+              msg += "**From:** #{email["fromAddress"]}"
+              send_notification(:zoho_triage, msg, channel: notify_channel, target: channel_id, agent: bot_name)
+            else
+              LOG.warn "[Zoho:Triage] No work item plugin handled card creation"
+              Handler.notify_match(email, { "label" => "Support Email (no card plugin)", "emoji" => "⚠️" })
+            end
+          rescue StandardError => e
+            LOG.error "[Zoho:Triage] Error creating card: #{e.message}\n#{e.backtrace.first(3).join("\n")}"
+            Handler.notify_match(email, { "label" => "Support Email", "emoji" => "🆘" })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/zoho/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Zoho
+      VERSION = "0.0.1"
+    end
+  end
+end

data/lib/brainiac/plugins/zoho.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "English"
+require "net/http"
+
+require_relative "zoho/version"
+require_relative "zoho/metadata"
+require_relative "zoho/cli"
+require_relative "zoho/config"
+require_relative "zoho/mail_api"
+require_relative "zoho/handler"
+require_relative "zoho/triage"
+
+module Brainiac
+  module Plugins
+    module Zoho
+      ZOHO_AUTH_SCOPES = "ZohoMail.messages.READ,ZohoMail.accounts.READ,ZohoMail.folders.READ"
+
+      class << self
+        # Called by Brainiac plugin system during server startup.
+        #
+        # @param app [Sinatra::Application] The running Brainiac server
+        def register(app)
+          Config.load!
+          setup_routes(app)
+          LOG.info "[Zoho] Plugin registered (webhook: /zoho)"
+        end
+
+        # Called after `brainiac install zoho` — creates config from template.
+        def post_install(brainiac_dir)
+          config_file = File.join(brainiac_dir, "zoho.json")
+          return if File.exist?(config_file)
+
+          template = File.expand_path("../../templates/zoho.json.example", __dir__)
+          if File.exist?(template)
+            FileUtils.cp(template, config_file)
+          else
+            default_config = {
+              "hook_secret" => nil,
+              "default_discord_channel_id" => "",
+              "notify_as" => "merlin",
+              "rules" => [],
+              "fallback" => { "enabled" => true, "label" => "Unmatched Email", "emoji" => "📬" }
+            }
+            File.write(config_file, JSON.pretty_generate(default_config))
+          end
+        end
+
+        private
+
+        def setup_routes(app)
+          app.post "/zoho" do
+            content_type :json
+            request.body.rewind
+            payload_body = request.body.read
+
+            # Zoho sends X-Hook-Secret on the very first request — capture and store it
+            hook_secret = request.env["HTTP_X_HOOK_SECRET"]
+            if hook_secret
+              Brainiac::Plugins::Zoho::Config.save_hook_secret(hook_secret)
+              LOG.info "[Zoho] Received and stored hook_secret from initial handshake"
+              halt 200, { status: "hook_secret_received" }.to_json
+            end
+
+            Brainiac::Plugins::Zoho.verify_signature!(request, payload_body)
+
+            email = JSON.parse(payload_body)
+            status_code, body = Brainiac::Plugins::Zoho::Handler.handle_webhook(email)
+            halt status_code, body
+          rescue JSON::ParserError => e
+            LOG.error "[Zoho] Invalid JSON: #{e.message}"
+            halt 400, { error: "Invalid JSON" }.to_json
+          rescue StandardError => e
+            LOG.error "[Zoho] Unhandled error: #{e.message}\n#{e.backtrace.first(5).join("\n")}"
+            halt 500, { error: e.message }.to_json
+          end
+
+          app.get "/zoho/auth" do
+            Brainiac::Plugins::Zoho::Config.reload!
+            api = Brainiac::Plugins::Zoho::Config.api_section
+            halt 500, "Missing client_id in zoho.json api section" unless api["client_id"]
+
+            redirect_uri = "#{request.base_url}/zoho/callback"
+            query_params = URI.encode_www_form(
+              scope: ZOHO_AUTH_SCOPES,
+              client_id: api["client_id"],
+              response_type: "code",
+              access_type: "offline",
+              redirect_uri: redirect_uri,
+              prompt: "consent"
+            )
+            redirect "https://accounts.zoho.com/oauth/v2/auth?#{query_params}"
+          end
+
+          app.get "/zoho/callback" do
+            content_type :html
+            code = params["code"]
+            halt 400, "No authorization code received" unless code
+
+            Brainiac::Plugins::Zoho::Config.reload!
+            api = Brainiac::Plugins::Zoho::Config.api_section
+            redirect_uri = "#{request.base_url}/zoho/callback"
+
+            uri = URI(Brainiac::Plugins::Zoho::MailApi::ZOHO_TOKEN_URL)
+            res = Net::HTTP.post_form(uri, {
+                                        "grant_type" => "authorization_code",
+                                        "client_id" => api["client_id"],
+                                        "client_secret" => api["client_secret"],
+                                        "code" => code,
+                                        "redirect_uri" => redirect_uri
+                                      })
+
+            data = JSON.parse(res.body)
+            if data["refresh_token"]
+              Brainiac::Plugins::Zoho::Config.config["api"] ||= {}
+              Brainiac::Plugins::Zoho::Config.config["api"]["refresh_token"] = data["refresh_token"]
+              Brainiac::Plugins::Zoho::MailApi.store_token(data["access_token"])
+              Brainiac::Plugins::Zoho::Config.save_config!
+              LOG.info "[Zoho:OAuth] Stored refresh_token and access_token"
+
+              unless Brainiac::Plugins::Zoho::Config.api_section["account_id"]
+                acct_uri = URI(Brainiac::Plugins::Zoho::MailApi::ZOHO_MAIL_API_BASE.to_s)
+                http = Net::HTTP.new(acct_uri.host, acct_uri.port)
+                http.use_ssl = true
+                req = Net::HTTP::Get.new(acct_uri)
+                req["Authorization"] = "Zoho-oauthtoken #{data["access_token"]}"
+                acct_res = http.request(req)
+                acct_data = JSON.parse(acct_res.body)
+                if (account_id = acct_data.dig("data", 0, "accountId"))
+                  Brainiac::Plugins::Zoho::Config.config["api"]["account_id"] = account_id
+                  Brainiac::Plugins::Zoho::Config.save_config!
+                  LOG.info "[Zoho:OAuth] Auto-fetched account_id: #{account_id}"
+                end
+              end
+
+              "<h1>✅ Zoho OAuth Complete</h1><p>Refresh token and account_id saved to zoho.json. You can close this tab.</p>"
+            else
+              LOG.error "[Zoho:OAuth] Token exchange failed: #{data}"
+              "<h1>❌ OAuth Failed</h1><pre>#{data.to_json}</pre>"
+            end
+          rescue StandardError => e
+            LOG.error "[Zoho:OAuth] Error: #{e.message}"
+            "<h1>❌ Error</h1><pre>#{e.message}</pre>"
+          end
+        end
+      end
+
+      # Verify the X-Hook-Signature header (base64 HMAC-SHA256 of the raw body).
+      def self.verify_signature!(request, payload_body)
+        signature = request.env["HTTP_X_HOOK_SIGNATURE"]
+        return unless signature
+
+        secret = Config.hook_secret
+        halt 500, { error: "No hook_secret configured — waiting for initial Zoho handshake" }.to_json unless secret
+
+        computed = Base64.strict_encode64(OpenSSL::HMAC.digest("sha256", secret, payload_body))
+        halt 403, { error: "Invalid Zoho signature" }.to_json unless Rack::Utils.secure_compare(signature, computed)
+      end
+    end
+  end
+end

data/lib/brainiac_zoho.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "brainiac/plugins/zoho"

data/templates/zoho.json.example

@@ -0,0 +1,27 @@
+{
+  "hook_secret": null,
+  "default_discord_channel_id": "YOUR_DISCORD_CHANNEL_ID",
+  "notify_as": "merlin",
+  "rules": [
+    {
+      "label": "Item Sold",
+      "enabled": true,
+      "from_contains": "",
+      "to_contains": "",
+      "subject_contains": "sold",
+      "body_contains": "",
+      "exclude_words": [],
+      "emoji": "💰",
+      "discord_channel_id": null,
+      "notify_as": null
+    }
+  ],
+  "fallback": {
+    "enabled": true,
+    "label": "Unmatched Email",
+    "emoji": "📬",
+    "exclude_words": [],
+    "discord_channel_id": null,
+    "notify_as": null
+  }
+}

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification
+name: brainiac-zoho
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Andy Davis
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: brainiac
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.9
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.9
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.25'
+description: Zoho Mail integration for Brainiac — receives email webhooks, matches
+  rules, sends notifications, and optionally triages support emails into work items.
+  Includes OAuth flow for Zoho Mail API access.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/brainiac/plugins/zoho.rb
+- lib/brainiac/plugins/zoho/cli.rb
+- lib/brainiac/plugins/zoho/config.rb
+- lib/brainiac/plugins/zoho/handler.rb
+- lib/brainiac/plugins/zoho/mail_api.rb
+- lib/brainiac/plugins/zoho/metadata.rb
+- lib/brainiac/plugins/zoho/triage.rb
+- lib/brainiac/plugins/zoho/version.rb
+- lib/brainiac_zoho.rb
+- templates/zoho.json.example
+homepage: https://github.com/stowzilla/brainiac-zoho
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Zoho Mail webhook plugin for Brainiac
+test_files: []