keywright-router 0.0.1__py3-none-any.whl

keywright_router/__init__.py

@@ -0,0 +1,9 @@
+"""Keywright router: watches a mailbox through Keywright and acts on what arrives.
+
+The router is an ordinary Keywright agent. It holds no mail password and no provider key:
+it reads and sends mail through the brokered `email` MCP server, asks the LLM gateway only
+when a rule needs a label or a draft, and every call it makes is checked against the rules
+the human set for its token. Routing itself is plain boolean logic over the message.
+"""
+
+__version__ = "0.0.1"

keywright_router/__main__.py

@@ -0,0 +1,83 @@
+"""keywright-router run|check|dry-run [--config PATH]
+
+  run       poll forever (the container's command)
+  check     validate the rules file and exit
+  access    print the standing access the rules need (as Keywright qualifies the calls) and ask
+            for what is missing in one request; approve it with Always allow
+  dry-run   one pass over today's unread mail: route each message and print the calls it would
+            make, without making them or recording anything. Reads and labels still go through
+            Keywright, so they are audited like any other call.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import sys
+
+from .config import ConfigError, load
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="keywright-router", description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("command", choices=["run", "check", "access", "dry-run"])
+    ap.add_argument("--config", default="/config/rules.yaml")
+    ap.add_argument("--log-level", default="INFO")
+    a = ap.parse_args(argv)
+    logging.basicConfig(level=a.log_level.upper(), format="%(asctime)s %(levelname)s %(message)s")
+    try:
+        cfg = load(a.config)
+    except ConfigError as e:
+        print(f"config error: {e}", file=sys.stderr)
+        return 2
+    if a.command == "check":
+        print(f"ok: {len(cfg.rules)} rules, {len(cfg.unmatched)} unmatched actions, "
+              f"llm {'used (' + str(cfg.model) + ')' if cfg.uses_llm else 'not used'}")
+        return 0
+
+    from .router import Router
+    if a.command == "access":
+        return asyncio.run(_access(cfg))
+    if a.command == "run":
+        asyncio.run(Router(cfg).run_forever())
+        return 0
+    return asyncio.run(_dry_run(cfg))
+
+
+async def _access(cfg) -> int:
+    from . import access
+    from .kw import Keywright
+
+    status, rid, patterns = await access.ensure(Keywright(cfg.kw_url, cfg.kw_token, cfg.session), cfg)
+    for p in patterns:
+        print(p)
+    print(f"{status}{' ' + rid if rid else ''}", file=sys.stderr)
+    return 0 if status in ("approved", "pending") else 1
+
+
+async def _dry_run(cfg) -> int:
+    from .kw import Pending
+    from .router import Router
+
+    router = Router(cfg)
+    for meta in await router.unread():
+        msg = await router.fetch(str(meta["email_id"]))
+        if msg is None:
+            continue
+        try:
+            job = await router.plan(msg)
+        except Pending as p:
+            print(f"{msg.key}: needs approval first ({p.request_id})")
+            continue
+        seen = " (already handled)" if router.store.has(msg.key) else ""
+        print(f"\n{msg.key}{seen}  {msg.subject!r} from {msg.sender_address}")
+        for s in job.steps:
+            print("  ", json.dumps({k: v for k, v in s.items() if k != "reason"})[:400])
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

keywright_router/access.py

@@ -0,0 +1,114 @@
+"""The standing access the rules need, asked for in one request instead of rule by rule.
+
+The paths are built the way Keywright qualifies the calls themselves (the same `classify_mcp`,
+the resource's own argument keys), so an "Always allow" on the request is exactly as wide as the
+rules file and no wider. Two things are left out on purpose:
+
+- a send or forward whose resource does not qualify calls by `recipients`: allowing the tool
+  would allow any recipient, so those calls keep asking one by one;
+- replies (the recipient is the sender of each message) and templated argument values (they
+  differ per message): the paths that would name them are dropped, so the human sees them per call.
+
+Model access is never part of it: an LLM approval is a timed lease with a spend ceiling, and a
+standing model rule is made in the UI.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from keywright.classify import classify_mcp
+
+from .config import PLACEHOLDER, Config
+from .kw import Keywright
+
+log = logging.getLogger("keywright_router")
+
+RECIPIENT_KEYS = ("recipients", "cc", "bcc")
+
+
+def needed(cfg: Config, arg_keys: dict[str, list[str]]) -> list[str]:
+    """Every path the rules will call with fixed arguments, qualified by each server's argument keys."""
+    acct = {"account_name": cfg.account}
+    calls: list[tuple[str, str, dict[str, Any]]] = [
+        (cfg.server, "list_emails_metadata", acct),
+        (cfg.server, "get_emails_content", acct),
+    ]
+    actions = [a for r in cfg.rules for a in r.do] + list(cfg.unmatched)
+    if actions:
+        calls.append((cfg.server, "mark_emails_as_read", acct))
+    if cfg.done_folder or any("move" in a for a in actions):
+        calls.append((cfg.server, "move_emails", acct))
+    email_keys = set(arg_keys.get(cfg.server) or [])
+    for action in actions:
+        kind, spec = next(iter(action.items()))
+        if kind in ("forward", "send"):
+            if "recipients" not in email_keys:
+                log.info("%s is not qualified by recipients on %s: %s calls will ask each time",
+                         kind, cfg.server, kind)
+                continue
+            tool = "forward_email" if kind == "forward" else "send_email"
+            calls.append((cfg.server, tool, {**acct, "recipients": list(spec["to"])}))
+        elif kind == "mcp":
+            server, tool = spec["tool"].split("__", 1)
+            raw, fixed = spec.get("args", {}), _literal(spec.get("args", {})) or {}
+            for key in arg_keys.get(server) or []:
+                if _lookup(raw, key) is not None and _lookup(fixed, key) is None:
+                    log.warning("%s qualifies %s by %s, which this rule fills from the message: "
+                                "that call will ask every time", server, tool, key)
+            calls.append((server, tool, fixed))
+    out: list[str] = []
+    for server, tool, args in calls:
+        keys = arg_keys.get(server)
+        if keys is None:
+            log.warning("no MCP resource named %r in Keywright; skipping %s", server, tool)
+            continue
+        for p in classify_mcp(server, tool, args, keys):
+            if p not in out:
+                out.append(p)
+    return out
+
+
+def _lookup(args: dict[str, Any], key: str) -> Any:
+    cur: Any = args
+    for part in key.split("."):
+        if not isinstance(cur, dict) or part not in cur:
+            return None
+        cur = cur[part]
+    return cur
+
+
+def _literal(value: Any) -> Any:
+    """Arguments as the human can pre-approve them: a templated value is unknown until a message
+    arrives, so it is removed and never qualifies the path."""
+    if isinstance(value, str):
+        return None if PLACEHOLDER.search(value) else value
+    if isinstance(value, dict):
+        return {k: v for k, v in ((k, _literal(v)) for k, v in value.items()) if v is not None}
+    if isinstance(value, list):
+        return [v for v in (_literal(v) for v in value) if v is not None] or None
+    return value
+
+
+async def argument_keys(kw: Keywright) -> dict[str, list[str]]:
+    data = await kw.call_access("access_list_resources", {})
+    out = {}
+    for r in data.get("resources") or []:
+        if r.get("kind") == "mcp":
+            out[str(r["resource"]).split("/", 1)[1]] = list(r.get("argument_keys") or [])
+    return out
+
+
+async def ensure(kw: Keywright, cfg: Config) -> tuple[str, str | None, list[str]]:
+    """Ask once for whatever the rules need that is not yet allowed. Returns (status, request_id, patterns):
+    approved when nothing is missing, pending with the request to watch, or denied."""
+    patterns = needed(cfg, await argument_keys(kw))
+    if not patterns:
+        return "approved", None, []
+    data = await kw.call_access("access_request", {
+        "patterns": patterns, "wait_seconds": 0,
+        "reason": f"mail router: standing access for its {len(cfg.rules)} rule(s). Choose Always allow "
+                  "to make these rules; anything else it does keeps asking per call.",
+    })
+    return str(data.get("status") or data.get("error") or "unknown"), data.get("request_id"), patterns

keywright_router/config.py

@@ -0,0 +1,241 @@
+"""The rules file: where the mail is, which model labels it, and what to do when a rule matches.
+
+Loaded once at start and validated completely, so a typo fails the container at boot instead
+of on the first message that happens to reach that rule.
+
+Recipients and tool names are literals. Message text reaches a call only through `{{field}}`
+placeholders in free-text values (a subject, a body, a tool argument), never as an address or
+a tool: a message cannot choose who hears about it or what runs.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+PREDICATES = {"from", "to", "subject", "subject_matches", "body", "body_matches", "has_attachment", "label"}
+COMBINATORS = {"all", "any", "not"}
+ACTIONS = {"reply", "send", "forward", "mcp", "attention", "move", "mark_read"}
+FIELDS = {"from", "to", "subject", "date", "body", "label", "email_id", "rule"}
+PLACEHOLDER = re.compile(r"\{\{\s*([a-z_]+)\s*\}\}")
+ADDRESS = re.compile(r"^[^@\s<>{}]+@[^@\s<>{}]+\.[^@\s<>{}]+$")
+
+
+class ConfigError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Rule:
+    name: str
+    when: Any
+    do: list[dict[str, Any]]
+    stop: bool = False
+
+
+@dataclass(frozen=True)
+class Config:
+    kw_url: str
+    kw_token: str
+    session: str
+    server: str
+    account: str
+    mailbox: str
+    poll_seconds: int
+    done_folder: str | None
+    since: str | None
+    gateway: str | None
+    model: str | None
+    labels: tuple[str, ...]
+    max_body_chars: int
+    rules: tuple[Rule, ...]
+    unmatched: tuple[dict[str, Any], ...]
+    state_path: Path
+    pending_hours: float
+    uses_llm: bool = field(default=False)
+
+
+def load(path: str | os.PathLike[str], env: dict[str, str] | None = None) -> Config:
+    env = dict(os.environ if env is None else env)
+    try:
+        raw = yaml.safe_load(Path(path).read_text()) or {}
+    except (OSError, yaml.YAMLError) as e:
+        raise ConfigError(f"{path}: {e}") from e
+    if not isinstance(raw, dict):
+        raise ConfigError(f"{path}: expected a mapping at the top level")
+    kw = raw.get("keywright") or {}
+    mail = raw.get("email") or {}
+    llm = raw.get("llm") or {}
+
+    token = env.get("KW_TOKEN", "")
+    if not token:
+        raise ConfigError("KW_TOKEN is not set; the router's Keywright token comes from the environment only")
+    labels = tuple(str(x) for x in llm.get("labels") or [])
+    if labels and "unclear" not in labels:
+        labels = (*labels, "unclear")
+
+    if mail.get("since"):
+        try:
+            datetime.fromisoformat(str(mail["since"]))
+        except ValueError as e:
+            raise ConfigError(f"email.since: {e} (use 2026-09-28 or 2026-09-28T09:00:00+00:00)") from e
+    rules = tuple(_rule(i, r, labels) for i, r in enumerate(raw.get("rules") or []))
+    names = [r.name for r in rules]
+    if len(set(names)) != len(names):
+        raise ConfigError("rule names must be unique")
+    unmatched = tuple(_action("unmatched", i, a) for i, a in enumerate(raw.get("unmatched") or []))
+
+    drafts = any(isinstance(spec, dict) and "llm" in spec
+                 for a in [*(a for r in rules for a in r.do), *unmatched] for spec in a.values())
+    uses_llm = drafts or any(_mentions_label(r.when) for r in rules)
+    gateway, model = llm.get("gateway"), llm.get("model")
+    if uses_llm and not (gateway and model):
+        raise ConfigError("a rule uses `label` or an `llm:` draft, so llm.gateway and llm.model are required")
+    if any(_mentions_label(r.when) for r in rules) and not labels:
+        raise ConfigError("a rule tests `label`, so llm.labels must list the labels the model may choose")
+
+    return Config(
+        kw_url=env.get("KW_URL") or kw.get("url") or "http://keywright:8700",
+        kw_token=token,
+        session=str(kw.get("session") or "keywright-router"),
+        server=str(mail.get("server") or "email"),
+        account=_required(mail, "account", "email"),
+        mailbox=str(mail.get("mailbox") or "INBOX"),
+        poll_seconds=max(15, int(mail.get("poll_seconds") or 60)),
+        done_folder=mail.get("done_folder") or None,
+        since=str(mail["since"]) if mail.get("since") else None,
+        gateway=gateway,
+        model=model,
+        labels=labels,
+        max_body_chars=int(llm.get("max_body_chars") or 6000),
+        rules=rules,
+        unmatched=unmatched,
+        state_path=Path(env.get("ROUTER_STATE") or raw.get("state") or "/data/router.db"),
+        pending_hours=float(raw.get("pending_hours") or 6),
+        uses_llm=uses_llm,
+    )
+
+
+def _required(section: dict, key: str, where: str) -> str:
+    value = section.get(key)
+    if not value:
+        raise ConfigError(f"{where}.{key} is required")
+    return str(value)
+
+
+def _rule(i: int, raw: Any, labels: tuple[str, ...]) -> Rule:
+    if not isinstance(raw, dict) or not raw.get("name"):
+        raise ConfigError(f"rules[{i}]: each rule needs a name")
+    name = str(raw["name"])
+    if "when" not in raw:
+        raise ConfigError(f"rule {name}: `when` is required (`when: {{all: []}}` matches every message)")
+    _condition(name, raw["when"], labels)
+    do = raw.get("do") or []
+    if not isinstance(do, list) or not do:
+        raise ConfigError(f"rule {name}: `do` must be a non-empty list of actions")
+    return Rule(name=name, when=raw["when"], do=[_action(name, j, a) for j, a in enumerate(do)],
+                stop=bool(raw.get("stop", False)))
+
+
+def _condition(rule: str, cond: Any, labels: tuple[str, ...]) -> None:
+    if not isinstance(cond, dict) or not cond:
+        raise ConfigError(f"rule {rule}: a condition is a non-empty mapping, got {cond!r}")
+    for key, value in cond.items():
+        if key in ("all", "any"):
+            if not isinstance(value, list):
+                raise ConfigError(f"rule {rule}: `{key}` takes a list of conditions")
+            for c in value:
+                _condition(rule, c, labels)
+        elif key == "not":
+            _condition(rule, value, labels)
+        elif key in ("subject_matches", "body_matches"):
+            try:
+                re.compile(str(value))
+            except re.error as e:
+                raise ConfigError(f"rule {rule}: bad regex in {key}: {e}") from e
+        elif key == "has_attachment":
+            if not isinstance(value, bool):
+                raise ConfigError(f"rule {rule}: has_attachment is true or false")
+        elif key == "label":
+            wanted = value if isinstance(value, list) else [value]
+            unknown = [w for w in wanted if w not in labels]
+            if unknown:
+                raise ConfigError(f"rule {rule}: label {unknown} is not in llm.labels {list(labels)}")
+        elif key not in PREDICATES:
+            raise ConfigError(f"rule {rule}: unknown condition `{key}` "
+                              f"(known: {sorted(PREDICATES | COMBINATORS)})")
+
+
+def _mentions_label(cond: Any) -> bool:
+    if not isinstance(cond, dict):
+        return False
+    for key, value in cond.items():
+        if key == "label":
+            return True
+        if key in ("all", "any") and any(_mentions_label(c) for c in value):
+            return True
+        if key == "not" and _mentions_label(value):
+            return True
+    return False
+
+
+def _action(rule: str, j: int, raw: Any) -> dict[str, Any]:
+    where = f"rule {rule} action {j}"
+    if not isinstance(raw, dict) or len(raw) != 1:
+        raise ConfigError(f"{where}: an action is a one-key mapping such as `reply: {{text: ...}}`")
+    kind, spec = next(iter(raw.items()))
+    if kind not in ACTIONS:
+        raise ConfigError(f"{where}: unknown action `{kind}` (known: {sorted(ACTIONS)})")
+    if kind in ("reply", "send", "forward"):
+        if not isinstance(spec, dict):
+            raise ConfigError(f"{where}: `{kind}` takes a mapping")
+        if kind in ("send", "forward"):
+            to = spec.get("to")
+            to = [to] if isinstance(to, str) else to
+            if not to or not all(isinstance(a, str) and ADDRESS.match(a) for a in to):
+                raise ConfigError(f"{where}: `{kind}.to` must be one or more literal addresses; "
+                                  "a recipient never comes from the message")
+            spec = {**spec, "to": list(to)}
+        if kind == "send" and not spec.get("subject"):
+            raise ConfigError(f"{where}: `send.subject` is required")
+        if kind in ("reply", "send") and ("text" in spec) == ("llm" in spec):
+            raise ConfigError(f"{where}: `{kind}` needs exactly one of `text` (a template) or `llm` (an instruction)")
+        _templates(where, spec, skip={"to"})
+    elif kind == "mcp":
+        if not isinstance(spec, dict) or not isinstance(spec.get("tool"), str) or "__" not in spec["tool"]:
+            raise ConfigError(f"{where}: `mcp.tool` is the brokered name, <server>__<tool>")
+        if PLACEHOLDER.search(spec["tool"]):
+            raise ConfigError(f"{where}: `mcp.tool` must be literal")
+        if not isinstance(spec.get("args", {}), dict):
+            raise ConfigError(f"{where}: `mcp.args` is a mapping")
+        _templates(where, spec.get("args", {}))
+    elif kind == "attention":
+        if not isinstance(spec, str) or not spec:
+            raise ConfigError(f"{where}: `attention` is the message template")
+        _templates(where, {"attention": spec})
+    elif kind == "move":
+        if not isinstance(spec, str) or not spec or PLACEHOLDER.search(spec):
+            raise ConfigError(f"{where}: `move` takes a literal folder name")
+    elif kind == "mark_read":
+        spec = True
+    return {kind: spec}
+
+
+def _templates(where: str, spec: Any, skip: set[str] = frozenset()) -> None:
+    if isinstance(spec, dict):
+        for k, v in spec.items():
+            if k not in skip:
+                _templates(where, v)
+    elif isinstance(spec, list):
+        for v in spec:
+            _templates(where, v)
+    elif isinstance(spec, str):
+        for name in PLACEHOLDER.findall(spec):
+            if name not in FIELDS:
+                raise ConfigError(f"{where}: unknown placeholder {{{{{name}}}}} (known: {sorted(FIELDS)})")

keywright_router/kw.py

@@ -0,0 +1,99 @@
+"""The router's only way out: brokered MCP calls and the LLM gateway, both through Keywright.
+
+Calls never wait on the human (`_wait_seconds: 0`, `X-Keywright-Wait: 0`). A call that needs
+approval comes back as Pending with the request id; the router parks the job and asks
+`access_status` about that id on later polls instead of repeating the call, so one message
+puts one prompt on the phone however long it takes to answer.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+from keywright import transport
+from keywright.config import Profile
+
+
+class KwError(Exception):
+    """The call was refused, denied, locked or failed; retrying the same call will not help."""
+
+    def __init__(self, kind: str, detail: dict[str, Any] | None = None):
+        self.kind = kind
+        self.detail = detail or {}
+        super().__init__(f"{kind}: {json.dumps(self.detail)[:300]}")
+
+
+class Pending(Exception):
+    """Waiting on the human; `request_id` is the one to poll."""
+
+    def __init__(self, request_id: str, patterns: list[str] | None = None):
+        self.request_id = request_id
+        self.patterns = patterns or []
+        super().__init__(f"approval pending: {request_id}")
+
+
+@dataclass
+class Keywright:
+    url: str
+    token: str
+    session: str
+    timeout: float = 120.0
+
+    @property
+    def profile(self) -> Profile:
+        return Profile(name="router", url=self.url, token=self.token)
+
+    async def call(self, tool: str, args: dict[str, Any], reason: str) -> dict[str, Any]:
+        """One brokered tool call. Returns the structured payload; raises Pending or KwError."""
+        result = await transport.acall(self.profile, self.session, tool,
+                                       {**args, "_reason": reason, "_wait_seconds": 0},
+                                       read_timeout=self.timeout)
+        data = transport.payload(result)
+        if getattr(result, "is_error", False):
+            kind = data.get("error") if isinstance(data.get("error"), str) else "upstream_error"
+            if kind == "approval_required" and data.get("request_id"):
+                raise Pending(data["request_id"], data.get("patterns"))
+            raise KwError(kind, data)
+        return data
+
+    async def call_access(self, tool: str, args: dict[str, Any]) -> dict[str, Any]:
+        """One of Keywright's own tools (access_list_resources, access_request): the payload as it
+        comes, errors included, since their answers are states rather than failures."""
+        result = await transport.acall(self.profile, self.session, tool, args, read_timeout=30.0)
+        return transport.payload(result)
+
+    async def status(self, request_id: str) -> str:
+        """pending | approved | denied | expired | not_found."""
+        result = await transport.acall(self.profile, self.session, "access_status", {"request_id": request_id},
+                                       read_timeout=30.0)
+        data = transport.payload(result)
+        return str(data.get("status") or data.get("error") or "not_found")
+
+    async def attention(self, message: str, context: str) -> None:
+        await transport.acall(self.profile, self.session, "request_attention",
+                              {"message": message[:500], "context": context[:200]}, read_timeout=30.0)
+
+    async def chat(self, gateway: str, model: str, messages: list[dict[str, str]], reason: str,
+                   max_tokens: int = 800) -> str:
+        headers = {"Authorization": f"Bearer {self.token}", "X-Keywright-Session": self.session,
+                   "X-Keywright-Wait": "0", "X-Keywright-Reason": reason[:200]}
+        body = {"model": model, "messages": messages, "temperature": 0, "max_tokens": max_tokens}
+        async with httpx.AsyncClient(timeout=self.timeout) as http:
+            r = await http.post(f"{self.url.rstrip('/')}/llm/{gateway}/v1/chat/completions",
+                                json=body, headers=headers)
+        try:
+            data = r.json()
+        except ValueError:
+            data = {}
+        if r.status_code != 200:
+            err = data.get("error") if isinstance(data.get("error"), dict) else {}
+            if err.get("code") == "approval_required" and err.get("request_id"):
+                raise Pending(err["request_id"], [f"llm/{gateway}/model/{model}"])
+            raise KwError(str(err.get("code") or f"http_{r.status_code}"), {"message": err.get("message")})
+        try:
+            return str(data["choices"][0]["message"]["content"] or "")
+        except (KeyError, IndexError, TypeError) as e:
+            raise KwError("bad_llm_response", {"body": str(data)[:300]}) from e