agent-core-inbound 0.8.2__py3-none-any.whl

agent_core_inbound/__init__.py

@@ -0,0 +1,4 @@
+"""Inbound notifications — deny-by-default external-event router.
+
+See docs/superpowers/specs/2026-06-20-inbound-notifications-design.md.
+"""

agent_core_inbound/_path.py

@@ -0,0 +1,39 @@
+"""Dotted-path resolver for the GitHubConnector matching engine.
+
+Walks a nested dict by splitting a dotted path into keys. Returns the
+sentinel ``MISSING`` for any path that doesn't resolve cleanly —
+including paths through non-dict cursor values, missing keys, or the
+empty path. Falsy values (False, 0, "", None, [], {}) are NOT treated
+as missing; they're real values the resolver returns directly.
+"""
+from __future__ import annotations
+
+from typing import Any, Final
+
+
+class _MissingSentinel:
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "MISSING"
+
+
+MISSING: Final = _MissingSentinel()
+
+
+def resolve_path(payload: dict[str, Any], path: str) -> Any:
+    """Resolve a dotted path against a nested dict.
+
+    Returns ``MISSING`` for any path that doesn't fully resolve.
+    """
+    if not path:
+        return MISSING
+    cursor: Any = payload
+    for key in path.split("."):
+        if not isinstance(cursor, dict) or key not in cursor:
+            return MISSING
+        cursor = cursor[key]
+    return cursor
+
+
+__all__ = ["MISSING", "resolve_path"]

agent_core_inbound/audit.py

@@ -0,0 +1,67 @@
+"""JSONL audit log for inbound-notifications router.
+
+One line per classification. Allow lines carry tier + reason +
+rule_id; Deny lines carry only the timestamp + source + target.
+Deny intentionally does NOT serialize the event body so a denied
+inbound leaves no privacy-sensitive trace.
+"""
+import json
+from collections.abc import Callable
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from agent_core_inbound.types import Allow
+
+
+def _default_clock() -> datetime:
+    return datetime.now(UTC)
+
+
+class AuditLog:
+    """Append-only JSONL writer keyed by absolute path.
+
+    ``clock`` is injectable so tests can pin the timestamp without
+    monkey-patching ``datetime.now``. Parent directories are created
+    on first write.
+    """
+
+    def __init__(
+        self,
+        *,
+        path: Path,
+        clock: Callable[[], datetime] = _default_clock,
+    ) -> None:
+        self._path = path
+        self._clock = clock
+
+    def record_allow(
+        self,
+        *,
+        connector_name: str,
+        target_being: str,
+        verdict: Allow,
+        rule_id: str,
+    ) -> None:
+        self._write({
+            "ts": self._clock().isoformat(),
+            "source": connector_name,
+            "to": target_being,
+            "verdict": "allow",
+            "tier": verdict.tier.value,
+            "rule_id": rule_id,
+            "reason": verdict.reason,
+        })
+
+    def record_deny(self, *, connector_name: str, target_being: str) -> None:
+        self._write({
+            "ts": self._clock().isoformat(),
+            "source": connector_name,
+            "to": target_being,
+            "verdict": "deny",
+        })
+
+    def _write(self, entry: dict[str, Any]) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        with self._path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(entry, separators=(",", ":")) + "\n")

agent_core_inbound/endpoint.py

@@ -0,0 +1,214 @@
+"""Daemon endpoint wrapper for the inbound-notifications router.
+
+Wires the FastAPI Funnel handler + Router into the bus runner via the
+``register_endpoint_types`` hookimpl (see ``plugin.py``).
+
+agent_core.yaml shape:
+
+  endpoints:
+    - type: inbound.github
+      name: inbound
+      params:
+        target_being: wren
+        listen_host: 127.0.0.1
+        listen_port: 8765
+        webhook_secret_env: FOREMAN_GITHUB_WEBHOOK_SECRET
+        github_allowance_path: ~/.wren/.config/inbound/github-allowance.toml
+        audit_log_path: ~/.wren/state/inbound-audit.jsonl
+        rate_limit_per_minute: 30
+
+Tailscale Funnel is configured OUT-OF-PROCESS via the operator's
+`tailscale funnel <port>` command pointing at ``listen_port``. The
+endpoint binds to ``listen_host`` (default 127.0.0.1) so the only
+public reach is through the tailnet-issued Funnel URL.
+
+Inbound is push-only — no peer endpoint addresses envelopes to it on
+the bus — so ``deliver`` just warns + acks anything that arrives.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import uvicorn
+
+from agent_core_credentials.secrets import SecretNotFoundError
+from agent_core_credentials.secrets import get as get_secret
+from agent_core_inbound.audit import AuditLog
+from agent_core_inbound.funnel_handler import build_funnel_app
+from agent_core_inbound.github_connector import GitHubConnector
+from agent_core_inbound.router import Router
+
+if TYPE_CHECKING:
+    from agent_core.bus.envelope import Envelope
+    from agent_core.bus.handle import BusHandle
+
+
+log = logging.getLogger(__name__)
+
+
+class InboundEndpoint:
+    """Daemon-lifecycle wrapper for the inbound-notifications router."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        target_being: str,
+        listen_host: str,
+        listen_port: int,
+        webhook_secret_env: str,
+        github_allowance_path: str,
+        audit_log_path: str,
+        rate_limit_per_minute: int = 30,
+    ) -> None:
+        self.name = name  # Protocol requires `name` attribute
+        self._target_being = target_being
+        self._listen_host = listen_host
+        self._listen_port = listen_port
+        self._webhook_secret_env = webhook_secret_env
+        self._github_allowance_path = github_allowance_path
+        self._audit_log_path = audit_log_path
+        self._rate_limit_per_minute = rate_limit_per_minute
+
+        # Validate secret at construction (fail-loud at config-load,
+        # not at first GitHub delivery).
+        try:
+            secret = get_secret(webhook_secret_env)
+        except SecretNotFoundError:
+            raise RuntimeError(
+                f"inbound endpoint {name!r}: env var {webhook_secret_env} not set "
+                f"(needed for GitHub webhook HMAC signature verification)"
+            ) from None
+        self._webhook_secret = secret.encode("utf-8")
+
+        # Defer Router + funnel app construction to start(); they need
+        # the BusHandle for bus_publish_adapter.
+        self._handle: BusHandle | None = None
+        self._server: uvicorn.Server | None = None
+        self._serve_task: asyncio.Task | None = None
+
+    async def start(self, bus: BusHandle) -> None:
+        """Bus is ready — build the Router/app and start uvicorn."""
+        self._handle = bus
+
+        connector = GitHubConnector(
+            config_path=Path(self._github_allowance_path).expanduser(),
+            principal_being=self._target_being,
+        )
+        audit = AuditLog(path=Path(self._audit_log_path).expanduser())
+        router = Router(
+            connectors={"github": connector},
+            bus_publish=self._bus_publish_adapter,
+            audit=audit,
+            rate_limits={
+                ("github", self._target_being): (self._rate_limit_per_minute, 60.0)
+            },
+        )
+        app = build_funnel_app(
+            router=router,
+            webhook_secret=self._webhook_secret,
+            target_being=self._target_being,
+        )
+        config = uvicorn.Config(
+            app,
+            host=self._listen_host,
+            port=self._listen_port,
+            log_level="info",
+            access_log=False,
+        )
+        self._server = uvicorn.Server(config)
+        self._serve_task = asyncio.create_task(self._server.serve())
+        log.info(
+            "InboundEndpoint(name=%s) started on %s:%s",
+            self.name,
+            self._listen_host,
+            self._listen_port,
+        )
+
+    async def deliver(self, envelope: Envelope) -> None:
+        """Inbound is push-only — no peer addresses envelopes here.
+
+        * Before start (_handle is None): raises EndpointUnavailable so the bus
+          requeues the envelope (transient — the endpoint is not yet ready).
+        * After start (_handle is not None): raises RuntimeError so the bus
+          dead-letters the misrouted envelope.  Acking would falsely mark the
+          envelope as "successfully delivered" and leave no DLQ record.
+        """
+        if self._handle is None:
+            from agent_core.bus.protocol import EndpointUnavailable
+            raise EndpointUnavailable(
+                f"inbound endpoint {self.name!r} not started"
+            )
+        log.warning(
+            "InboundEndpoint(name=%s) received unexpected envelope kind=%s from=%s — dead-lettering",
+            self.name,
+            envelope.kind,
+            envelope.from_,
+        )
+        raise RuntimeError(
+            f"inbound endpoint {self.name!r} received unexpected envelope kind={envelope.kind!r} "
+            f"from={envelope.from_!r}; inbound is push-only"
+        )
+
+    async def stop(self) -> None:
+        """Graceful shutdown — set should_exit and await up to 5s."""
+        if self._server is not None:
+            self._server.should_exit = True
+        if self._serve_task is not None:
+            try:
+                await asyncio.wait_for(self._serve_task, timeout=5.0)
+            except TimeoutError:
+                self._serve_task.cancel()
+        self._handle = None
+        log.info("InboundEndpoint(name=%s) stopped", self.name)
+
+    def _bus_publish_adapter(
+        self,
+        *,
+        to: str,
+        kind: str,
+        payload: dict[str, Any],
+        urgency: str,
+    ) -> None:
+        """Bridge Router's bus_publish callable to BusHandle.publish.
+
+        Router calls this sync from inside the FastAPI async handler, so
+        we are guaranteed to be on a running event loop. BusHandle.publish
+        is async; we schedule it as a task and return immediately so the
+        Router's sync path doesn't block on the bus enqueue.
+
+        Construction notes:
+        * "Notification" is a BUILTIN_KIND — the Envelope validator
+          requires the payload to validate against ``NotificationPayload``
+          (a raw dict would be rejected). We model_validate here so any
+          payload shape bug surfaces at the call site rather than as an
+          opaque Envelope construction error.
+        * ``from_`` is left default — the bus stamps it to ``self.name``
+          via BusHandle on publish.
+        * ``urgency`` is narrowed to ``Literal["green","yellow","red"]``
+          at the Envelope layer; the Router passes a str (tier.value),
+          so we trust the connector's tier vocabulary here.
+        """
+        if self._handle is None:
+            raise RuntimeError(
+                f"inbound endpoint {self.name!r}: bus_publish called before start"
+            )
+
+        from agent_core.bus.envelope import Envelope, NotificationPayload
+
+        notification = NotificationPayload.model_validate(payload)
+        envelope = Envelope(
+            id=uuid.uuid4().hex,
+            correlation_id=uuid.uuid4().hex,
+            to=to,
+            kind=kind,
+            payload=notification,
+            urgency=urgency,
+            created_at=datetime.now(UTC),
+        )
+        self._handle.spawn(self._handle.publish(envelope), name="inbound-bus-publish")

agent_core_inbound/funnel_handler.py

@@ -0,0 +1,126 @@
+"""Tailscale Funnel HTTPS endpoint — receives GitHub webhooks.
+
+Validates X-Hub-Signature-256 via HMAC-SHA256 of the raw body with
+the operator-configured webhook secret. Translates the payload into
+a generic GitHubEvent and hands it to Router.receive(). The connector's
+match engine walks ``raw`` via dotted paths, so every webhook event
+parses successfully here — including events GitHub introduces after
+this code shipped. Filtering happens at the connector layer, not here.
+
+Bad/missing signatures return 401 — but GitHub treats any non-2xx as a
+delivery failure and retries, which means a misconfigured secret will
+retry forever; the operator's deploy checklist must verify the secret
+pair end-to-end before going live.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from datetime import UTC, datetime
+
+from fastapi import FastAPI, Header, HTTPException, Request, status
+
+from agent_core_inbound.github_event import GitHubEvent
+from agent_core_inbound.router import Router
+
+
+def build_funnel_app(
+    *,
+    router: Router,
+    webhook_secret: bytes,
+    target_being: str,
+) -> FastAPI:
+    """Construct the FastAPI app with the GitHub webhook handler bound.
+
+    Returned app exposes POST /github. Hand to uvicorn / the daemon
+    endpoint wrapper for serving.
+    """
+    app = FastAPI(docs_url=None, redoc_url=None)
+
+    @app.post("/github", status_code=status.HTTP_204_NO_CONTENT)
+    async def receive_github(
+        request: Request,
+        x_github_event: str | None = Header(default=None),
+        x_github_delivery: str | None = Header(default=None),
+        x_hub_signature_256: str | None = Header(default=None),
+    ) -> None:
+        raw = await request.body()
+        if not _verify_signature(raw, x_hub_signature_256, webhook_secret):
+            raise HTTPException(status_code=401, detail="bad signature")
+
+        # Guard against signed-but-malformed JSON bodies. Returning 400
+        # (rather than letting json.JSONDecodeError raise a 500) tells
+        # GitHub to stop retrying — a malformed body won't be fixed by
+        # redelivery, and 5xx triggers the indefinite retry loop noted
+        # in the module docstring.
+        try:
+            payload = json.loads(raw) if raw else {}
+        except json.JSONDecodeError:
+            raise HTTPException(status_code=400, detail="malformed JSON body")
+
+        delivery_id = x_github_delivery or ""
+        # event_id falls back to event_type + repo + action when GitHub
+        # omits X-GitHub-Delivery so the router's de-dupe key is still
+        # stable.
+        if delivery_id:
+            event_id = f"github-{delivery_id}"
+        else:
+            repo_full_name = (payload.get("repository") or {}).get(
+                "full_name", "",
+            )
+            action = payload.get("action", "")
+            event_id = (
+                f"github-{repo_full_name}-{x_github_event or ''}-{action}"
+            )
+
+        event = _parse_event(
+            {"X-GitHub-Event": x_github_event or ""},
+            raw,
+            event_id=event_id,
+        )
+
+        router.receive(
+            connector_name="github",
+            target_being=target_being,
+            event=event,
+        )
+
+    return app
+
+
+def _verify_signature(
+    body: bytes,
+    header_value: str | None,
+    secret: bytes,
+) -> bool:
+    if header_value is None or not header_value.startswith("sha256="):
+        return False
+    expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
+    presented = header_value.removeprefix("sha256=")
+    return hmac.compare_digest(expected, presented)
+
+
+def _parse_event(
+    headers: dict[str, str],
+    body: bytes,
+    *,
+    event_id: str,
+) -> GitHubEvent:
+    """Parse a GitHub webhook into a generic event.
+
+    ``headers`` is the request headers map (case-insensitive lookup of
+    ``X-GitHub-Event`` to identify the event type). ``body`` is the raw
+    request body; we parse it as JSON and preserve the dict in
+    ``GitHubEvent.raw`` for downstream matchers.
+    """
+    event_type = headers.get("X-GitHub-Event") or headers.get("x-github-event") or ""
+    payload = json.loads(body) if body else {}
+    return GitHubEvent(
+        event_id=event_id,
+        landed_at=datetime.now(UTC),
+        event_type=event_type,
+        action=payload.get("action", ""),
+        repo_full_name=(payload.get("repository") or {}).get("full_name", ""),
+        raw=payload,
+    )

agent_core_inbound/github_allowance.py

@@ -0,0 +1,95 @@
+"""TOML-driven GitHub allowance policy.
+
+The principal being (Wren) edits this file directly to manage their
+GitHub inbound rules. The router watches mtime and reloads on change
+(see Task 10).
+"""
+from __future__ import annotations
+
+import tomllib
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from agent_core_inbound.types import Tier
+
+
+class AllowRule(BaseModel):
+    """One allowance rule. First-match-wins in classify()."""
+
+    rule_id: str = Field(min_length=1)
+    event: str = Field(min_length=1)
+    tier: Tier
+    reason: str = Field(min_length=1)
+
+    # Optional match constraints. All present constraints must match
+    # for the rule to apply. Missing constraints are wildcard.
+    repo: str | None = None
+    reviewer: str | None = None
+    label_name: str | None = None
+    match: dict[str, Any] | None = None
+
+    model_config = ConfigDict(extra="forbid")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _reject_body_contains(cls, data: Any) -> Any:
+        if isinstance(data, dict) and "body_contains" in data:
+            raise ValueError(
+                "AllowRule field 'body_contains' was removed in v2. "
+                "Use `match` with an exact-equality dotted path; substring "
+                "matching is deferred to v2.1 (`match_contains` operator)."
+            )
+        return data
+
+    @model_validator(mode="after")
+    def _translate_shortcuts(self) -> AllowRule:
+        # object.__setattr__ avoids Pydantic v2's re-validation trigger
+        # that self.x = ... would cause from inside an after-validator.
+        # Merge reviewer / label_name shortcuts into match, then null them.
+        # Existing match entries take precedence on key collision (shouldn't
+        # happen in practice — these are distinct field names).
+        added: dict[str, Any] = {}
+        if self.reviewer is not None:
+            added["requested_reviewer.login"] = self.reviewer
+            object.__setattr__(self, "reviewer", None)
+        if self.label_name is not None:
+            added["label.name"] = self.label_name
+            object.__setattr__(self, "label_name", None)
+        if added:
+            merged = dict(added)
+            if self.match is not None:
+                merged.update(self.match)
+            object.__setattr__(self, "match", merged)
+        return self
+
+
+class AllowanceConfig(BaseModel):
+    """The complete allowance policy."""
+
+    allow: list[AllowRule] = Field(default_factory=list)
+
+    model_config = ConfigDict(extra="forbid")
+
+    @model_validator(mode="after")
+    def _enforce_unique_rule_ids(self) -> AllowanceConfig:
+        counts = Counter(r.rule_id for r in self.allow)
+        dups = [rid for rid, n in counts.items() if n > 1]
+        if dups:
+            raise ValueError(f"duplicate rule_id(s): {', '.join(sorted(dups))}")
+        return self
+
+
+def load_allowance(path: Path) -> AllowanceConfig:
+    """Read + validate the TOML at ``path``.
+
+    Returns an empty config (allow=[]) for an empty or missing-rules
+    file. Validation errors propagate as ``pydantic.ValidationError``
+    for the caller to log / surface.
+    """
+    if not path.exists():
+        return AllowanceConfig(allow=[])
+    data = tomllib.loads(path.read_text(encoding="utf-8"))
+    return AllowanceConfig.model_validate(data)