galvanize 0.2.0__tar.gz

galvanize-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: ci
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Import smoke
+        run: python -c "import galvanize; import galvanize.cli, galvanize.mcp, galvanize.daemon"
+      - name: CLI boots
+        run: galvanize --version
+      - name: Tests
+        run: pytest -q

galvanize-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+.build-notes.md
+design-ref/
+publish/

galvanize-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jarvis Lai
+
+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.

galvanize-0.2.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.5
+Name: galvanize
+Version: 0.2.0
+Summary: Event-driven activation points for AI agents: wake a fresh Hermes (or any CLI agent) session when something happens.
+Project-URL: Homepage, https://github.com/jarvis959/galvanize
+Author: Jarvis Lai
+License: MIT
+License-File: LICENSE
+Keywords: agents,automation,events,hermes,triggers,webhooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: imap-tools<2,>=1.10
+Requires-Dist: keyring<26,>=24
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: watchdog<7,>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+![galvanize: wake your agents when the world moves](assets/galvanize-infographic.png)
+
+**Wake your AI agent when something happens, not on a timer.**
+
+galvanize watches the real world (new mail in an inbox, a file landing in a folder, a git commit, a webhook call, an event from a script) and wakes a fresh AI agent session the moment one of those things occurs, with a prompt you wrote. Until now, the only event an agent could see was the clock: "trigger me when X" always became an hourly cron poll, because polling was the only surface the agent had. galvanize puts real event triggers directly into the agent's own tool list (native plugin for Hermes, MCP server for Claude Code and Codex), so when you say "wake me when resumes land", the agent wires an actual push trigger instead. Passwords go to your OS keyring, each trigger starts watching in seconds, and results arrive wherever you asked (Telegram, Discord, or just the log).
+
+## Install
+
+Works on Windows, macOS, and Linux (Python 3.10+). No cloning needed — one command installs straight from GitHub:
+
+```bash
+pipx install "git+https://github.com/jarvis959/galvanize.git"
+# or: uv tool install --from "git+https://github.com/jarvis959/galvanize.git" galvanize
+# or: pip install git+https://github.com/jarvis959/galvanize.git
+```
+
+Then run setup once:
+
+```bash
+galvanize init
+```
+
+`init` enables the Hermes webhook platform (backs up your config first), installs the agent plugin, registers the daemon to start at login, and auto-registers the MCP tool surface into Claude Code / Codex if it finds them on this machine. Everything is confirmed on screen and reversible; `--yes` accepts defaults.
+
+After that, the whole surface is five verbs:
+
+```bash
+galvanize add folder ~/watch --wake hermes             # + a live test fire
+galvanize add imap you@gmail.com --wake hermes         # app-password to keyring
+galvanize status           # watching? last fire, errors, health
+galvanize doctor           # deep health check
+galvanize test cad-drops   # inject a synthetic event through the real path
+```
+
+## Why
+
+Every "trigger me when X" conversation defaults to an hourly cron poller, because polling is the only surface the agent can see. galvanize puts event triggers *in the agent's own tool list*, so when you say "wake me when resumes land", the agent wires a real push trigger instead of a poll job.
+
+- **Fresh sessions, not thread injections.** Each event spawns a clean one-shot run: no context pollution, results delivered where you asked.
+- **Management everywhere cron is managed.** Dashboard `/triggers` tab, `/triggers` slash command, `hermes triggers` CLI, agent tools, plus `galvanize status` / `doctor` / `daemon`: all surfaces, one ops core.
+- **Push email that survives real life.** IDLE with 25-min re-arm, UID dedupe, reconnect catch-up, keyring-held credentials, and a `migrate hermes-cron` command that converts your existing email pollers.
+- **Zero-inbound-port webhooks.** Optional user-owned Cloudflare Worker relay (`relay/worker.js`): services POST to your URL, your laptop pulls the queue.
+
+## Working with each harness
+
+### Hermes
+
+`galvanize init` does the setup: enables `platforms.webhook` in your `config.yaml` (backup saved first), pip-installs the package into the interpreter Hermes runs in, copies the plugin into `~/.hermes/plugins` and enables it. Restart the Hermes gateway once to load the webhook platform; the `trigger_*` tools appear in new sessions. From then on, "wake me when a file lands in ~/cad-drops" creates a real trigger in conversation.
+
+### Claude Code / Codex
+
+`init` writes the MCP server entry into `~/.claude.json` / `~/.codex/config.toml` automatically when it finds them (Codex gets `default_tools_approval_mode = "approve"` pre-declared, as newer Codex builds otherwise hide the tools). New session: `trigger_add` and friends are in the tool list. Wake presets:
+
+```bash
+galvanize add folder ~/inbox --wake claude   # claude -p "{prompt}"
+galvanize add folder ~/inbox --wake codex    # codex exec (sandbox pre-declared)
+galvanize add git-hook ~/code/myrepo --wake codex   # wake Codex on commits
+```
+
+### Any other CLI agent
+
+```bash
+galvanize add folder ~/watch --wake shell --command 'myagent run "{prompt}"'
+```
+
+## Daily use
+
+Triggers the agent creates itself with its `trigger_add` tool are the primary path; the CLI is the no-agent fallback. Both write the same `~/.galvanize/triggers.yaml`, and the dashboard tab manages what either creates (creation stays conversation-first by design).
+
+## Development
+
+```bash
+git clone https://github.com/jarvis959/galvanize && cd galvanize
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"   # Scripts/ on Windows
+.venv/bin/pytest                     # unit suite; live-lane + docker tests skip cleanly
+```
+
+The live Hermes-lane test runs inside a Hermes checkout's venv (`pytest tests/test_live_hermes_lane.py`); the IMAP suite drives a GreenMail container and skips when Docker is unavailable.
+
+MIT licensed. Built for the Hermes ecosystem; architecture is harness-neutral.

galvanize-0.2.0/README.md

@@ -0,0 +1,80 @@
+![galvanize: wake your agents when the world moves](assets/galvanize-infographic.png)
+
+**Wake your AI agent when something happens, not on a timer.**
+
+galvanize watches the real world (new mail in an inbox, a file landing in a folder, a git commit, a webhook call, an event from a script) and wakes a fresh AI agent session the moment one of those things occurs, with a prompt you wrote. Until now, the only event an agent could see was the clock: "trigger me when X" always became an hourly cron poll, because polling was the only surface the agent had. galvanize puts real event triggers directly into the agent's own tool list (native plugin for Hermes, MCP server for Claude Code and Codex), so when you say "wake me when resumes land", the agent wires an actual push trigger instead. Passwords go to your OS keyring, each trigger starts watching in seconds, and results arrive wherever you asked (Telegram, Discord, or just the log).
+
+## Install
+
+Works on Windows, macOS, and Linux (Python 3.10+). No cloning needed — one command installs straight from GitHub:
+
+```bash
+pipx install "git+https://github.com/jarvis959/galvanize.git"
+# or: uv tool install --from "git+https://github.com/jarvis959/galvanize.git" galvanize
+# or: pip install git+https://github.com/jarvis959/galvanize.git
+```
+
+Then run setup once:
+
+```bash
+galvanize init
+```
+
+`init` enables the Hermes webhook platform (backs up your config first), installs the agent plugin, registers the daemon to start at login, and auto-registers the MCP tool surface into Claude Code / Codex if it finds them on this machine. Everything is confirmed on screen and reversible; `--yes` accepts defaults.
+
+After that, the whole surface is five verbs:
+
+```bash
+galvanize add folder ~/watch --wake hermes             # + a live test fire
+galvanize add imap you@gmail.com --wake hermes         # app-password to keyring
+galvanize status           # watching? last fire, errors, health
+galvanize doctor           # deep health check
+galvanize test cad-drops   # inject a synthetic event through the real path
+```
+
+## Why
+
+Every "trigger me when X" conversation defaults to an hourly cron poller, because polling is the only surface the agent can see. galvanize puts event triggers *in the agent's own tool list*, so when you say "wake me when resumes land", the agent wires a real push trigger instead of a poll job.
+
+- **Fresh sessions, not thread injections.** Each event spawns a clean one-shot run: no context pollution, results delivered where you asked.
+- **Management everywhere cron is managed.** Dashboard `/triggers` tab, `/triggers` slash command, `hermes triggers` CLI, agent tools, plus `galvanize status` / `doctor` / `daemon`: all surfaces, one ops core.
+- **Push email that survives real life.** IDLE with 25-min re-arm, UID dedupe, reconnect catch-up, keyring-held credentials, and a `migrate hermes-cron` command that converts your existing email pollers.
+- **Zero-inbound-port webhooks.** Optional user-owned Cloudflare Worker relay (`relay/worker.js`): services POST to your URL, your laptop pulls the queue.
+
+## Working with each harness
+
+### Hermes
+
+`galvanize init` does the setup: enables `platforms.webhook` in your `config.yaml` (backup saved first), pip-installs the package into the interpreter Hermes runs in, copies the plugin into `~/.hermes/plugins` and enables it. Restart the Hermes gateway once to load the webhook platform; the `trigger_*` tools appear in new sessions. From then on, "wake me when a file lands in ~/cad-drops" creates a real trigger in conversation.
+
+### Claude Code / Codex
+
+`init` writes the MCP server entry into `~/.claude.json` / `~/.codex/config.toml` automatically when it finds them (Codex gets `default_tools_approval_mode = "approve"` pre-declared, as newer Codex builds otherwise hide the tools). New session: `trigger_add` and friends are in the tool list. Wake presets:
+
+```bash
+galvanize add folder ~/inbox --wake claude   # claude -p "{prompt}"
+galvanize add folder ~/inbox --wake codex    # codex exec (sandbox pre-declared)
+galvanize add git-hook ~/code/myrepo --wake codex   # wake Codex on commits
+```
+
+### Any other CLI agent
+
+```bash
+galvanize add folder ~/watch --wake shell --command 'myagent run "{prompt}"'
+```
+
+## Daily use
+
+Triggers the agent creates itself with its `trigger_add` tool are the primary path; the CLI is the no-agent fallback. Both write the same `~/.galvanize/triggers.yaml`, and the dashboard tab manages what either creates (creation stays conversation-first by design).
+
+## Development
+
+```bash
+git clone https://github.com/jarvis959/galvanize && cd galvanize
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"   # Scripts/ on Windows
+.venv/bin/pytest                     # unit suite; live-lane + docker tests skip cleanly
+```
+
+The live Hermes-lane test runs inside a Hermes checkout's venv (`pytest tests/test_live_hermes_lane.py`); the IMAP suite drives a GreenMail container and skips when Docker is unavailable.
+
+MIT licensed. Built for the Hermes ecosystem; architecture is harness-neutral.

galvanize-0.2.0/galvanize/__init__.py

@@ -0,0 +1,7 @@
+"""Galvanize — event-driven activation points for AI agents.
+
+Wake a fresh agent session when something happens in the world:
+a file lands in a folder, a webhook fires, a script emits an event.
+"""
+
+__version__ = "0.2.0"

galvanize-0.2.0/galvanize/__main__.py

@@ -0,0 +1,8 @@
+"""Allow ``python -m galvanize`` as an alias for the CLI entry point."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

galvanize-0.2.0/galvanize/autostart.py

@@ -0,0 +1,211 @@
+"""Start-at-login install for the galvanize daemon.
+
+User-facing behavior (PLAN §5): after `galvanize init`, the daemon is
+registered to start at login and running right now. Mechanisms per OS:
+  Windows : Task Scheduler, per-user onlogon task (no admin, hidden window)
+  Linux   : systemd user unit (+ enable --now; lingering hint if no session)
+  macOS   : LaunchAgent plist + launchctl bootstrap
+
+Everything is per-user, reversible (`daemon remove`), and prints exactly
+what it did. The task/agent runs `galvanize run`; hot state lives in
+~/.galvanize so a reboot resumes all triggers.
+"""
+
+from __future__ import annotations
+
+import os
+import plistlib
+import subprocess
+import sys
+from pathlib import Path
+
+from .paths import ensure_home
+
+
+TASK_NAME = "GalvanizeTriggerDaemon"
+UNIT_NAME = "galvanize"
+
+
+def _galvanize_run_cmd() -> list[str]:
+    """Interpreter + args that run `galvanize run` with no console window.
+
+    Handles both launch shapes: `python -m galvanize` (sys.executable is the
+    interpreter) and the installed `galvanize.exe` launcher (find python(.w)
+    next to it). Prefers pythonw.exe on Windows — windowless.
+    """
+    exe = Path(sys.executable)
+    if exe.name.lower() not in ("python.exe", "pythonw.exe"):
+        # frozen entry-point launcher -> sibling interpreter in Scripts/..
+        cand = exe.parent.parent / "Scripts" / "python.exe"
+        if not cand.exists():
+            cand = exe.parent / "python.exe"
+        if cand.exists():
+            exe = cand
+    if os.name == "nt":
+        windowless = exe.with_name("pythonw.exe")
+        if windowless.exists():
+            exe = windowless
+    return [str(exe), "-m", "galvanize.cli", "run"]
+
+
+# ------------------------------------------------------------------ Windows
+
+def _startup_lnk() -> Path:
+    return Path(os.environ.get("APPDATA", str(Path.home()))) / \
+        "Microsoft" / "Windows" / "Start Menu" / "Programs" / "Startup" / "Galvanize.lnk"
+
+
+def _write_startup_shortcut() -> None:
+    """Shell:startup .lnk via PowerShell WScript.Shell (no admin needed)."""
+    target, *arglist = _galvanize_run_cmd()
+    args = " ".join(arglist)
+    lnk = _startup_lnk()
+    ps = (
+        "$s=(New-Object -ComObject WScript.Shell).CreateShortcut('%s');"
+        "$s.TargetPath='%s';$s.Arguments='%s';$s.WorkingDirectory='%s';$s.WindowStyle=7;$s.Save()"
+        % (str(lnk).replace("'", "''"), target, args,
+           str(ensure_home()).replace("'", "''"))
+    )
+    subprocess.run(["powershell", "-NoProfile", "-Command", ps],
+                   capture_output=True, text=True, check=True)
+
+
+def _win_install() -> tuple[bool, list[str]]:
+    # Preferred: Startup-folder shortcut — per-user, no elevation.
+    try:
+        _write_startup_shortcut()
+        lines = ["✔ Daemon will start at login (Startup shortcut created)."]
+        # start it right now, detached, windowless
+        creationflags = 0x00000008 | 0x00000200  # DETACHED_PROCESS | NEW_PROCESS_GROUP
+        subprocess.Popen(_win_startup_cmd(), stdout=subprocess.DEVNULL,
+                         stderr=subprocess.DEVNULL, stdin=subprocess.DEVNULL,
+                         creationflags=creationflags)
+        lines.append("✔ Daemon started now.")
+        return True, lines
+    except Exception as e:
+        return False, [f"✖ Startup shortcut failed: {e}",
+                       "  Fallback: galvanize run in a terminal, or 'galvanize daemon install' as admin"]
+
+
+def _win_startup_cmd() -> list[str]:
+    """Direct detached run (pythonw -m galvanize.cli run)."""
+    return _galvanize_run_cmd()
+
+
+def _win_remove() -> tuple[bool, list[str]]:
+    ok = True
+    lines = []
+    lnk = _startup_lnk()
+    try:
+        lnk.unlink(missing_ok=True)
+        lines.append("✔ Removed Startup shortcut (won't start at login).")
+    except OSError as e:
+        ok = False
+        lines.append(f"✖ Could not remove Startup shortcut: {e}")
+    # also clear a legacy schtasks entry if one exists
+    subprocess.run(["schtasks", "/End", "/TN", TASK_NAME], capture_output=True)
+    subprocess.run(["schtasks", "/Delete", "/F", "/TN", TASK_NAME], capture_output=True)
+    return ok, lines
+
+
+def _win_installed() -> bool:
+    return _startup_lnk().exists()
+
+
+# ------------------------------------------------------------------ Linux
+
+def _unit_path() -> Path:
+    return Path.home() / ".config" / "systemd" / "user" / f"{UNIT_NAME}.service"
+
+
+def _linux_install() -> tuple[bool, list[str]]:
+    lines = []
+    exe = " ".join(_galvanize_run_cmd())
+    unit = (
+        "[Unit]\nDescription=Galvanize trigger daemon\n\n"
+        "[Service]\nExecStart=" + exe + "\nRestart=on-failure\n\n"
+        "[Install]\nWantedBy=default.target\n"
+    )
+    _unit_path().parent.mkdir(parents=True, exist_ok=True)
+    _unit_path().write_text(unit, encoding="utf-8")
+    p = subprocess.run(["systemctl", "--user", "enable", "--now", f"{UNIT_NAME}.service"],
+                       capture_output=True, text=True)
+    if p.returncode == 0:
+        return True, ["✔ systemd user service enabled and started.",
+                      "  (Server/logind headless: run 'loginctl enable-linger $USER' to keep it up at logout.)"]
+    return False, [f"✖ systemctl failed: {(p.stderr or p.stdout).strip()[:200]}",
+                   f"  Unit written to {_unit_path()} — enable manually."]
+
+
+def _linux_remove() -> tuple[bool, list[str]]:
+    subprocess.run(["systemctl", "--user", "disable", "--now", f"{UNIT_NAME}.service"],
+                   capture_output=True)
+    try:
+        _unit_path().unlink(missing_ok=True)
+    except OSError:
+        pass
+    return True, ["✔ systemd user service removed."]
+
+
+def _linux_installed() -> bool:
+    return _unit_path().exists()
+
+
+# ------------------------------------------------------------------ macOS
+
+def _plist_path() -> Path:
+    return Path.home() / "Library" / "LaunchAgents" / f"agent.galvanize.{UNIT_NAME}.plist"
+
+
+def _macos_install() -> tuple[bool, list[str]]:
+    plist = {
+        "Label": f"agent.galvanize.{UNIT_NAME}",
+        "ProgramArguments": _galvanize_run_cmd(),
+        "RunAtLoad": True,
+        "KeepAlive": {"SuccessfulExit": False},
+    }
+    _plist_path().parent.mkdir(parents=True, exist_ok=True)
+    with open(_plist_path(), "wb") as fh:
+        plistlib.dump(plist, fh)
+    p = subprocess.run(["launchctl", "bootstrap", f"gui/{os.getuid()}", str(_plist_path())],
+                       capture_output=True, text=True)
+    if p.returncode == 0 or "already loaded" in (p.stderr or "").lower():
+        return True, ["✔ LaunchAgent installed and loaded."]
+    return False, [f"✖ launchctl failed: {(p.stderr or p.stdout).strip()[:200]}"]
+
+
+def _macos_remove() -> tuple[bool, list[str]]:
+    subprocess.run(["launchctl", "bootout", f"gui/{os.getuid()}", str(_plist_path())],
+                   capture_output=True)
+    try:
+        _plist_path().unlink(missing_ok=True)
+    except OSError:
+        pass
+    return True, ["✔ LaunchAgent removed."]
+
+
+def _macos_installed() -> bool:
+    return _plist_path().exists()
+
+
+# ------------------------------------------------------------------ facade
+
+def _os() -> str:
+    if sys.platform == "win32":
+        return "win"
+    if sys.platform == "darwin":
+        return "macos"
+    return "linux"
+
+
+def install() -> tuple[bool, list[str]]:
+    ensure_home()
+    return {"win": _win_install, "linux": _linux_install, "macos": _macos_install}[_os()]()
+
+
+def remove() -> tuple[bool, list[str]]:
+    return {"win": _win_remove, "linux": _linux_remove, "macos": _macos_remove}[_os()]()
+
+
+def installed() -> bool:
+    return {"win": _win_installed, "linux": _linux_installed, "macos": _macos_installed}[_os()]()

galvanize-0.2.0/galvanize/bus.py

@@ -0,0 +1,76 @@
+"""The Trigger Bus: dedupe + cooldown, then dispatch.
+
+Every source funnels normalized events through here so the guards live in
+exactly one place:
+  - dedupe_key: repeated events carrying the same key collapse to one wake
+    (folder-watch double-fires, re-adding a file, source+lane overlap)
+  - cooldown_s: minimum seconds between two wakes for one trigger
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from typing import Dict, Optional, Tuple
+
+from . import dispatch as dispatch_mod
+from .config import Trigger, load_triggers
+from .events import Event
+from .template import render
+
+logger = logging.getLogger("galvanize.bus")
+
+
+class TriggerBus:
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._last_fire: Dict[str, float] = {}      # successful dispatches
+        self._last_attempt: Dict[str, float] = {}   # for cooldown throttling
+        self._seen_keys: Dict[str, Tuple[float, str]] = {}  # trigger -> (ts, key)
+
+    def _gate(self, t: Trigger, event: Event) -> Tuple[Optional[str], Optional[str]]:
+        """Return (skip_reason, pending_dedupe_key). skip_reason None -> fire."""
+        now = time.time()
+        pending: Optional[str] = None
+        with self._lock:
+            if t.dedupe_key:
+                key = render(t.dedupe_key, event.payload)
+                pending = key
+                prev = self._seen_keys.get(t.name)
+                if prev and prev[1] == key and (
+                    not t.cooldown_s or now - prev[0] < t.cooldown_s
+                ):
+                    return f"dedupe '{key}'", None
+            if t.cooldown_s:
+                last = self._last_attempt.get(t.name, 0.0)
+                if now - last < t.cooldown_s:
+                    return f"cooldown ({int(now - last)}s < {int(t.cooldown_s)}s)", None
+            self._last_attempt[t.name] = now
+        return None, pending
+
+    def handle(self, t: Trigger, event: Event) -> Tuple[bool, str]:
+        """Handle an event for a trigger. Returns (ok_or_skipped, detail)."""
+        if not t.enabled:
+            return True, "trigger disabled"
+        reason, pending_key = self._gate(t, event)
+        if reason:
+            logger.info("skip %s: %s", t.name, reason)
+            return True, f"skipped: {reason}"
+        prompt = render(t.prompt, event.payload)
+        ok, detail = dispatch_mod.dispatch(t, event, prompt)
+        if ok:
+            with self._lock:
+                self._last_fire[t.name] = time.time()
+                if pending_key is not None:
+                    self._seen_keys[t.name] = (time.time(), pending_key)
+        else:
+            logger.warning("dispatch failed for %s: %s", t.name, detail)
+        return ok, detail
+
+    def handle_named(self, trigger_name: str, event: Event) -> Tuple[bool, str]:
+        ts = load_triggers()
+        t = ts.get(trigger_name)
+        if t is None:
+            return False, f"unknown trigger '{trigger_name}'"
+        return self.handle(t, event)