dispatchbox 0.1.0__py3-none-any.whl

dispatchbox/__init__.py

@@ -0,0 +1,3 @@
+"""dispatchbox: a thin event router that hands work to coding agents on your own machines."""
+
+__version__ = "0.1.0"

dispatchbox/__main__.py

@@ -0,0 +1,127 @@
+"""Command line entry point: `python -m dispatchbox hub|worker|send|check`."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import socket
+import sys
+import urllib.error
+import urllib.request
+
+from . import __version__
+from .net import context_for
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="dispatchbox", description="Route events to coding agents on your own machines.")
+    p.add_argument("--version", action="version", version=__version__)
+    p.add_argument("-v", "--verbose", action="store_true")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    h = sub.add_parser("hub", help="run the hub (events in, tasks out)")
+    h.add_argument("--rules", default="rules.json")
+    h.add_argument("--db", default="dispatchbox.db")
+    h.add_argument("--host", default="127.0.0.1")
+    h.add_argument("--port", type=int, default=8787)
+    h.add_argument("--public-url", default=os.environ.get("DISPATCHBOX_PUBLIC_URL", ""),
+                   help="URL people use to reach the hub, used in notification links")
+
+    w = sub.add_parser("worker", help="run a worker that pulls tasks and runs agents")
+    w.add_argument("--hub", default=os.environ.get("DISPATCHBOX_HUB", "http://127.0.0.1:8787"))
+    w.add_argument("--name", default=socket.gethostname().split(".")[0])
+    w.add_argument("--slots", type=int, default=2, help="how many runs at once")
+    w.add_argument("--allow-dir", action="append", dest="allow_dirs",
+                   help="directory runs may use (repeatable); defaults to the current directory")
+    w.add_argument("--runners", default="claude,codex", help="comma list; add 'shell' to allow shell rules")
+    w.add_argument("--claude-bin", default="claude")
+    w.add_argument("--codex-bin", default="codex")
+
+    s = sub.add_parser("send", help="send one event to the hub")
+    s.add_argument("source")
+    s.add_argument("type")
+    s.add_argument("--subject", default="")
+    s.add_argument("--summary", default="")
+    s.add_argument("--link", default="")
+    s.add_argument("--payload", default="{}", help="JSON object")
+    s.add_argument("--hub", default=os.environ.get("DISPATCHBOX_HUB", "http://127.0.0.1:8787"))
+
+    c = sub.add_parser("check", help="validate a rules file and show which rule an event would hit")
+    c.add_argument("--rules", default="rules.json")
+    c.add_argument("--source")
+    c.add_argument("--type")
+    c.add_argument("--subject", default="")
+
+    args = p.parse_args(argv)
+    logging.basicConfig(level=logging.DEBUG if args.verbose else logging.INFO,
+                        format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+    token = os.environ.get("DISPATCHBOX_TOKEN", "")
+
+    if args.cmd == "hub":
+        from .hub import Hub
+        from .server import serve
+        from .chat import ChatError, adapters_from_env
+        hub = Hub(args.rules, args.db, public_url=args.public_url)
+        try:
+            hub.adapters = adapters_from_env(hub, dict(os.environ))
+        except ChatError as e:
+            print(f"Cannot start: {e}", file=sys.stderr)
+            return 2
+        srv = serve(hub, args.host, args.port, token, os.environ.get("DISPATCHBOX_GITHUB_SECRET", ""))
+        logging.getLogger("dispatchbox").info("hub listening on http://%s:%d with %d rules, %d schedules, chat: %s",
+                                        args.host, args.port, len(hub.config.rules), len(hub.config.schedules),
+                                        ", ".join(hub.adapters) or "none")
+        try:
+            srv.serve_forever()
+        except KeyboardInterrupt:
+            pass
+        return 0
+
+    if args.cmd == "worker":
+        from .worker import WorkerConfig, serve_worker
+        if not token:
+            print("Set DISPATCHBOX_TOKEN to the hub's token.", file=sys.stderr)
+            return 2
+        cfg = WorkerConfig(hub=args.hub, name=args.name, token=token, slots=args.slots,
+                           allow_dirs=args.allow_dirs or [os.getcwd()],
+                           runners=[r.strip() for r in args.runners.split(",") if r.strip()],
+                           claude_bin=args.claude_bin, codex_bin=args.codex_bin)
+        try:
+            serve_worker(cfg)
+        except KeyboardInterrupt:
+            pass
+        return 0
+
+    if args.cmd == "send":
+        body = {"source": args.source, "type": args.type, "subject": args.subject, "summary": args.summary,
+                "link": args.link, "payload": json.loads(args.payload)}
+        req = urllib.request.Request(args.hub.rstrip("/") + "/events", data=json.dumps(body).encode(), method="POST",
+                                     headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"})
+        try:
+            with urllib.request.urlopen(req, timeout=15, context=context_for(req.full_url)) as resp:
+                print(resp.read().decode())
+        except urllib.error.HTTPError as e:
+            print(f"{e.code}: {e.read().decode()}", file=sys.stderr)
+            return 1
+        return 0
+
+    if args.cmd == "check":
+        from .rules import load_config_file, normalize_event
+        try:
+            cfg = load_config_file(args.rules)
+        except Exception as e:
+            print(f"invalid: {e}", file=sys.stderr)
+            return 1
+        print(f"ok: {len(cfg.rules)} rules, {len(cfg.schedules)} schedules, dedupe window {cfg.dedupe_window}s")
+        if args.source and args.type:
+            ev = normalize_event({"source": args.source, "type": args.type, "subject": args.subject})
+            hits = cfg.match(ev)
+            print("matches: " + (", ".join(r.name for r in hits) if hits else "(none)"))
+        return 0
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dispatchbox/chat.py

@@ -0,0 +1,209 @@
+"""Shared plumbing for chat platforms (Feishu, Slack).
+
+An adapter does four things:
+  1. turns chat messages that mention the bot (or DM it) into dispatchbox events,
+  2. posts a decision card with one button per option when a run needs a human,
+  3. records the button click as a decision and updates the card in place,
+  4. replies in the original thread when a run that came from chat finishes.
+
+Platform specifics (auth, signatures, payload shapes, card formats) live in feishu.py and slack.py.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import urllib.error
+import urllib.request
+from typing import TYPE_CHECKING, Any, Callable
+
+from .hub import DECISION_MARK, STATUS_MARK, SUMMARY_MARK
+from .net import ssl_context
+
+if TYPE_CHECKING:
+    from .hub import Hub
+
+log = logging.getLogger("dispatchbox.chat")
+
+STATUS_LABEL = {
+    "succeeded": "✅ succeeded",
+    "failed": "❌ failed",
+    "lost": "⚠️ lost",
+    "awaiting_decision": "🟠 needs your decision",
+    "decided": "☑️ decided",
+}
+
+# (status, headers, body) returned to the HTTP layer
+Response = tuple[int, dict[str, str], bytes]
+
+
+def json_response(obj: Any, status: int = 200) -> Response:
+    return status, {"Content-Type": "application/json"}, json.dumps(obj, ensure_ascii=False).encode()
+
+
+def empty_response(status: int = 200) -> Response:
+    return status, {}, b""
+
+
+class ChatError(Exception):
+    pass
+
+
+def http_json(method: str, url: str, body: Any = None, headers: dict[str, str] | None = None,
+              timeout: float = 10) -> dict[str, Any]:
+    data = json.dumps(body, ensure_ascii=False).encode() if body is not None else None
+    req = urllib.request.Request(url, data=data, method=method,
+                                 headers={"Content-Type": "application/json; charset=utf-8", **(headers or {})})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout, context=ssl_context()) as resp:
+            raw = resp.read()
+    except urllib.error.HTTPError as e:
+        raw = e.read()
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError:
+            raise ChatError(f"{method} {url} -> HTTP {e.code}: {raw[:300]!r}") from e
+    return json.loads(raw) if raw else {}
+
+
+def in_background(fn: Callable[..., Any], *args: Any) -> None:
+    """Chat platforms want an answer within ~3 seconds, so slow work (API calls) runs on a thread."""
+    def run() -> None:
+        try:
+            fn(*args)
+        except Exception:
+            log.exception("background chat task failed")
+    threading.Thread(target=run, daemon=True).start()
+
+
+class ChatAdapter:
+    name = "chat"          # also the event source name and the URL suffix: /hooks/<name>
+
+    def __init__(self, hub: "Hub"):
+        self.hub = hub
+
+    # ---- configuration from the "chat" section of the rules file, re-read on every use so edits apply live
+
+    @property
+    def settings(self) -> dict[str, Any]:
+        # Chat requests are checked before ingest, so pick up allowlist edits here instead of
+        # waiting for the once-a-minute cron tick.
+        self.hub.reload_if_changed()
+        return (self.hub.config.chat or {}).get(self.name) or {}
+
+    def user_allowed(self, user_id: str, key: str = "allowed_users") -> bool:
+        """Nobody is allowed unless listed. "*" allows everyone in the workspace."""
+        allowed = self.settings.get(key)
+        if allowed is None and key == "approvers":
+            allowed = self.settings.get("allowed_users")
+        allowed = allowed or []
+        return "*" in allowed or user_id in allowed
+
+    # ---- hooks called by the hub
+
+    def notify(self, run: dict[str, Any], link: str) -> None:
+        raise NotImplementedError
+
+    def run_finished(self, run: dict[str, Any], link: str) -> None:
+        """Reply in the originating thread. Called for every run that reaches a resting state."""
+        raise NotImplementedError
+
+    def handle(self, headers: dict[str, str], body: bytes) -> Response:
+        """Handle a request to /hooks/<name>."""
+        raise NotImplementedError
+
+    # ---- helpers shared by adapters
+
+    def origin(self, run: dict[str, Any]) -> dict[str, Any] | None:
+        """The chat message this run (or the run it continues) came from, if it came from this platform."""
+        found = self._chat_origin(run, {self.name})
+        return found[1] if found else None
+
+    def from_chat(self, run: dict[str, Any]) -> bool:
+        """True if the run came from any connected chat platform. That platform answers in the
+        original conversation, so the others stay quiet instead of offering a second set of buttons."""
+        return self._chat_origin(run, set(self.hub.adapters) | {self.name}) is not None
+
+    def _chat_origin(self, run: dict[str, Any], sources: set[str]) -> tuple[str, dict[str, Any]] | None:
+        seen: set[int] = set()
+        cur: dict[str, Any] | None = run
+        while cur and cur["id"] not in seen:
+            seen.add(cur["id"])
+            for e in cur.get("events") or []:
+                if e["source"] in sources and isinstance(e.get("payload"), dict) and e["payload"].get("chat"):
+                    return e["source"], e["payload"]
+            parent = cur.get("parent_run") or cur.get("retry_of")
+            cur = self.hub.get_run(parent) if parent else None
+        return None
+
+    def decide_from_chat(self, run_id: int, choice: str, user_id: str) -> tuple[bool, str, dict[str, Any] | None]:
+        """Record a button click. Returns (ok, message for the clicker, run after the attempt)."""
+        from .hub import HubError
+        if not self.user_allowed(user_id, "approvers"):
+            log.warning("%s user %s tried to decide run %s but is not an approver", self.name, user_id, run_id)
+            return False, "You are not allowed to decide dispatchbox runs.", self.hub.get_run(run_id)
+        try:
+            self.hub.decide(run_id, choice, by=f"{self.name}:{user_id}")
+        except HubError as e:
+            return False, str(e), self.hub.get_run(run_id)
+        return True, f"Recorded: {choice}", self.hub.get_run(run_id)
+
+
+def decision_text(run: dict[str, Any]) -> tuple[str, str, list[str]]:
+    """(question, context, options) for a run awaiting a decision."""
+    req = run.get("decision_request") or {}
+    return str(req.get("question") or "The agent needs a decision."), str(req.get("context") or ""), \
+        [str(o) for o in (req.get("options") or [])][:5]
+
+
+def answer_text(run: dict[str, Any], limit: int) -> str:
+    """What the agent actually said, minus the DISPATCHBOX_* contract lines; the summary only if that is empty.
+    The answer is in the asker's language and has the detail; the summary is a one-liner for lists."""
+    lines = [l for l in (run.get("output_tail") or "").splitlines()
+             if not l.strip().startswith((DECISION_MARK, STATUS_MARK, SUMMARY_MARK))]
+    text = "\n".join(lines).strip() or str(run.get("summary") or "")
+    return text if len(text) <= limit else text[:limit - 1].rstrip() + "…"
+
+
+def status_line(run: dict[str, Any]) -> str:
+    return f"{STATUS_LABEL.get(run['status'], run['status'])} · run #{run['id']} · {run['rule']}"
+
+
+def decided_line(run: dict[str, Any]) -> str:
+    d = run.get("decision") or {}
+    who = str(d.get("by", "")).split(":", 1)[-1]
+    return f"Decision: {d.get('choice', '')}" + (f" (by {who})" if who else "")
+
+
+def adapters_from_env(hub: "Hub", env: dict[str, str]) -> dict[str, ChatAdapter]:
+    """Build the adapters whose credentials are present. A half-configured platform is an error, not a skip."""
+    adapters: dict[str, ChatAdapter] = {}
+
+    slack_keys = ("DISPATCHBOX_SLACK_BOT_TOKEN", "DISPATCHBOX_SLACK_SIGNING_SECRET")
+    have = [k for k in slack_keys if env.get(k)]
+    if have and len(have) != len(slack_keys):
+        missing = ", ".join(k for k in slack_keys if not env.get(k))
+        raise ChatError(f"Slack is half configured: set {missing} as well, or unset {', '.join(have)}")
+    if have:
+        from .slack import SlackAdapter
+        adapters["slack"] = SlackAdapter(hub, env["DISPATCHBOX_SLACK_BOT_TOKEN"], env["DISPATCHBOX_SLACK_SIGNING_SECRET"],
+                                         api_base=env.get("DISPATCHBOX_SLACK_API", "https://slack.com/api"))
+
+    feishu_keys = ("DISPATCHBOX_FEISHU_APP_ID", "DISPATCHBOX_FEISHU_APP_SECRET", "DISPATCHBOX_FEISHU_VERIFICATION_TOKEN")
+    have = [k for k in feishu_keys if env.get(k)]
+    if have and len(have) != len(feishu_keys):
+        missing = ", ".join(k for k in feishu_keys if not env.get(k))
+        raise ChatError(f"Feishu is half configured: set {missing} as well, or unset {', '.join(have)}")
+    if have:
+        from .feishu import API_BASE, TOKEN_URL, FeishuAdapter
+        adapters["feishu"] = FeishuAdapter(
+            hub, env["DISPATCHBOX_FEISHU_APP_ID"], env["DISPATCHBOX_FEISHU_APP_SECRET"], env["DISPATCHBOX_FEISHU_VERIFICATION_TOKEN"],
+            encrypt_key=env.get("DISPATCHBOX_FEISHU_ENCRYPT_KEY", ""),
+            api_base=env.get("DISPATCHBOX_FEISHU_API", API_BASE), token_url=env.get("DISPATCHBOX_FEISHU_TOKEN_URL", TOKEN_URL))
+
+    for name in adapters:
+        if not (hub.config.chat or {}).get(name):
+            log.warning("%s credentials are set but the rules file has no chat.%s section, so nobody is allowed "
+                        "to use it yet", name, name)
+    return adapters

dispatchbox/cron.py

@@ -0,0 +1,56 @@
+"""Minimal 5-field cron matcher: minute hour day-of-month month day-of-week.
+
+Supports `*`, `*/n`, `a`, `a-b`, `a-b/n` and comma lists. Day-of-week 0 and 7 are Sunday.
+When both day fields are restricted, a time matches if either one matches (classic cron rule).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+_RANGES = [(0, 59), (0, 23), (1, 31), (1, 12), (0, 7)]
+
+
+def _parse_field(text: str, lo: int, hi: int) -> set[int]:
+    values: set[int] = set()
+    for part in text.split(","):
+        step = 1
+        if "/" in part:
+            part, step_s = part.split("/", 1)
+            step = int(step_s)
+            if step <= 0:
+                raise ValueError(f"bad step in {text!r}")
+        if part == "*":
+            start, end = lo, hi
+        elif "-" in part:
+            a, b = part.split("-", 1)
+            start, end = int(a), int(b)
+        else:
+            start = int(part)
+            end = hi if step != 1 else start
+        if start < lo or end > hi or start > end:
+            raise ValueError(f"value out of range in {text!r}")
+        values.update(range(start, end + 1, step))
+    return values
+
+
+class Cron:
+    def __init__(self, expr: str):
+        fields = expr.split()
+        if len(fields) != 5:
+            raise ValueError(f"cron needs 5 fields, got {expr!r}")
+        self.expr = expr
+        parsed = [_parse_field(f, lo, hi) for f, (lo, hi) in zip(fields, _RANGES)]
+        self.minutes, self.hours, self.days, self.months, dows = parsed
+        self.dows = {d % 7 for d in dows}
+        self.day_restricted = fields[2] != "*"
+        self.dow_restricted = fields[4] != "*"
+
+    def matches(self, t: datetime) -> bool:
+        if t.minute not in self.minutes or t.hour not in self.hours or t.month not in self.months:
+            return False
+        dom_ok = t.day in self.days
+        dow_ok = (t.isoweekday() % 7) in self.dows
+        if self.day_restricted and self.dow_restricted:
+            return dom_ok or dow_ok
+        return dom_ok and dow_ok