bollard-ai 0.3.0__tar.gz

bollard_ai-0.3.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: bollard-ai
+Version: 0.3.0
+Summary: See, then govern, your AI agents — watch which apps they use, and enforce what they're allowed to do.
+Author: Bollard AI
+License: Proprietary
+Project-URL: Homepage, https://bollardai.com
+Keywords: bollard,ai agents,governance,observability,security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# bollard
+
+The one line that lets Bollard **see, then govern** your AI agents.
+
+Add it where your agents start up. By default it's **watch-only** — it notes which
+apps your agents use (Notion, Slack, Gmail, Xero, Drive, paid AI models), never what
+they read or write, and reports it to Bollard. When you protect an app in Bollard, the
+same install starts routing *that app's* calls through Bollard so each agent can only
+do what you allow — no code change. Every other app stays watch-only.
+
+Three promises, enforced in code:
+
+- **It can't break your agents.** Watch-only observes and, if anything goes wrong,
+  falls straight through to the real call. Enforcement is opt-in, per app, reversible.
+- **It can't slow them down.** It reports in the background on its own thread.
+- **It never sees your data or code.** It reads only the *envelope* of each call — the
+  destination and operation name. There is no code path that reads a request or
+  response body (see `bollard/_apps.py`).
+
+## Install
+
+```bash
+pip install bollard-ai
+```
+
+## Use it
+
+**One shared codebase** — wrap the command, no code change:
+
+```bash
+bollard watch --key BWATCH-XXXX-XXXX-XXXX -- python your_agents.py
+```
+
+**Separate projects** — add one line where each agent starts up:
+
+```python
+import bollard
+bollard.start(key="BWATCH-XXXX-XXXX-XXXX", agent="sales-follow-up")
+```
+
+## Enforcement (opt-in)
+
+Watching needs only your workspace key. To let Bollard *enforce* an agent (once you've
+protected an app in the dashboard), give that agent its own identity:
+
+```python
+bollard.start(key="BWATCH-...", agent="sales-follow-up", agent_token="boll_agt_...")
+```
+
+With an `agent_token`, calls to any **protected** app are routed through Bollard, which
+allows or blocks them against that agent's permissions. Apps you haven't protected stay
+watch-only. No `agent_token` → always watch-only. If Bollard can't be reached to confirm
+the policy, the agent stays watch-only — it never starts blocking off an unconfirmed rule.
+
+## Configuration
+
+`start()` reads these when the arguments are omitted:
+
+| Variable | Meaning |
+|---|---|
+| `BOLLARD_KEY` | your workspace key (`BWATCH-...`) |
+| `BOLLARD_AGENT` | optional name for this agent |
+| `BOLLARD_AGENT_TOKEN` | this agent's identity (`boll_agt_...`), for enforcement |
+| `BOLLARD_ENDPOINT` | override Bollard's base address (self-hosting / testing) |

bollard_ai-0.3.0/README.md

@@ -0,0 +1,64 @@
+# bollard
+
+The one line that lets Bollard **see, then govern** your AI agents.
+
+Add it where your agents start up. By default it's **watch-only** — it notes which
+apps your agents use (Notion, Slack, Gmail, Xero, Drive, paid AI models), never what
+they read or write, and reports it to Bollard. When you protect an app in Bollard, the
+same install starts routing *that app's* calls through Bollard so each agent can only
+do what you allow — no code change. Every other app stays watch-only.
+
+Three promises, enforced in code:
+
+- **It can't break your agents.** Watch-only observes and, if anything goes wrong,
+  falls straight through to the real call. Enforcement is opt-in, per app, reversible.
+- **It can't slow them down.** It reports in the background on its own thread.
+- **It never sees your data or code.** It reads only the *envelope* of each call — the
+  destination and operation name. There is no code path that reads a request or
+  response body (see `bollard/_apps.py`).
+
+## Install
+
+```bash
+pip install bollard-ai
+```
+
+## Use it
+
+**One shared codebase** — wrap the command, no code change:
+
+```bash
+bollard watch --key BWATCH-XXXX-XXXX-XXXX -- python your_agents.py
+```
+
+**Separate projects** — add one line where each agent starts up:
+
+```python
+import bollard
+bollard.start(key="BWATCH-XXXX-XXXX-XXXX", agent="sales-follow-up")
+```
+
+## Enforcement (opt-in)
+
+Watching needs only your workspace key. To let Bollard *enforce* an agent (once you've
+protected an app in the dashboard), give that agent its own identity:
+
+```python
+bollard.start(key="BWATCH-...", agent="sales-follow-up", agent_token="boll_agt_...")
+```
+
+With an `agent_token`, calls to any **protected** app are routed through Bollard, which
+allows or blocks them against that agent's permissions. Apps you haven't protected stay
+watch-only. No `agent_token` → always watch-only. If Bollard can't be reached to confirm
+the policy, the agent stays watch-only — it never starts blocking off an unconfirmed rule.
+
+## Configuration
+
+`start()` reads these when the arguments are omitted:
+
+| Variable | Meaning |
+|---|---|
+| `BOLLARD_KEY` | your workspace key (`BWATCH-...`) |
+| `BOLLARD_AGENT` | optional name for this agent |
+| `BOLLARD_AGENT_TOKEN` | this agent's identity (`boll_agt_...`), for enforcement |
+| `BOLLARD_ENDPOINT` | override Bollard's base address (self-hosting / testing) |

bollard_ai-0.3.0/bollard/__init__.py

@@ -0,0 +1,114 @@
+"""bollard — the one line that lets Bollard see, then govern, your AI agents.
+
+    import bollard
+    bollard.start(key="BWATCH-...")
+
+By default it's **watch-only**: it notes which apps your agents use (never what they
+read or write) and reports them to Bollard, changing nothing. It runs alongside your
+agent and fails silently, so it can't break your agents or slow them down.
+
+When you protect an app in Bollard *and* give an agent its own identity
+(`agent_token`), the same install starts routing that app's calls through Bollard so
+that agent can only do what you allow — no code change. Every other app, and every
+other agent, stays watch-only. Protection is opt-in, per agent, per app, and reversible
+from the dashboard.
+
+    bollard.start(key="BWATCH-...", agent="sales-bot", agent_token="boll_agt_...")
+
+If several agents run in the *same* process (a shared codebase), the package can't tell
+them apart on its own — mark each agent's run so calls are attributed (and enforced) to
+the right one:
+
+    with bollard.agent("sales-follow-up", token="boll_agt_..."):
+        run_the_agent()
+"""
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from ._context import agent  # noqa: F401  (public: the per-agent marker)
+from ._patch import install as _install, uninstall as _uninstall
+from ._policy import Policy
+from ._reporter import Reporter
+
+__version__ = "0.3.0"
+
+_DEFAULT_ENDPOINT = "https://api.bollardai.com"
+
+_reporter: Optional[Reporter] = None
+_policy: Optional[Policy] = None
+
+
+def start(key: Optional[str] = None, *, agent: Optional[str] = None,
+          agent_token: Optional[str] = None, endpoint: Optional[str] = None,
+          enforce: bool = True) -> None:
+    """Switch Bollard on. Safe to call once at startup; a second call is a no-op.
+
+    key:         your workspace key (starts with "BWATCH-"). Falls back to BOLLARD_KEY.
+    agent:       optional name for this agent (sharpens attribution). Falls back to
+                 BOLLARD_AGENT.
+    agent_token: this agent's own identity (starts with "boll_agt_"). Required for
+                 enforcement; omit it and the agent stays watch-only. Falls back to
+                 BOLLARD_AGENT_TOKEN.
+    endpoint:    override Bollard's base address (self-hosting / testing). Falls back
+                 to BOLLARD_ENDPOINT.
+    enforce:     set False to force watch-only even where an app is protected.
+    """
+    global _reporter, _policy
+    if _reporter is not None:
+        return  # already on
+
+    key = key or os.environ.get("BOLLARD_KEY") or os.environ.get("BOLLARD_WATCH_KEY")
+    if not key:
+        return  # nothing to do — never raise a misconfigured watcher into the agent
+    agent = agent or os.environ.get("BOLLARD_AGENT") or _default_agent_hint()
+    agent_token = agent_token or os.environ.get("BOLLARD_AGENT_TOKEN")
+    base = (endpoint or os.environ.get("BOLLARD_ENDPOINT")
+            or os.environ.get("BOLLARD_WATCH_ENDPOINT") or _DEFAULT_ENDPOINT).rstrip("/")
+
+    try:
+        reporter = Reporter(key=key, signal_url=base + "/watch/signal", agent=agent)
+        reporter.start()
+        policy = Policy(policy_url=base + "/watch/policy", gateway_base=base)
+        token = agent_token if enforce else None
+        if enforce:
+            # Fetch the process agent's policy up front (live from the first call), then
+            # run the background refresher — which also lazily fetches any agents marked
+            # mid-run with bollard.agent(name, token=...). Purely-watch installs (no token,
+            # no markers) make no policy calls: nothing is ever registered to fetch.
+            policy.prime(token)
+            policy.start()
+        _install(reporter, policy, agent, token)
+        _reporter, _policy = reporter, policy
+    except Exception:
+        _reporter = _policy = None  # any setup failure = stay out of the way entirely
+
+
+def stop() -> None:
+    """Stop and remove the hooks. Rarely needed; mainly for tests."""
+    global _reporter, _policy
+    _uninstall()
+    if _policy is not None:
+        try:
+            _policy.stop()
+        except Exception:
+            pass
+        _policy = None
+    if _reporter is not None:
+        try:
+            _reporter.flush_and_stop()
+        except Exception:
+            pass
+        _reporter = None
+
+
+def _default_agent_hint() -> Optional[str]:
+    try:
+        import sys
+        base = os.path.basename(sys.argv[0] or "") or "agent"
+        base = base.rsplit(".py", 1)[0]
+        host = os.environ.get("HOSTNAME") or ""
+        return f"{base}@{host}" if host else base or None
+    except Exception:
+        return None

bollard_ai-0.3.0/bollard/_apps.py

@@ -0,0 +1,85 @@
+"""Envelope reading — turn a call's *destination* into "which app, which operation".
+
+We look at three things and nothing else: the destination host, the request method,
+and the URL path. We NEVER read the request body, the response body, headers, query
+strings, or any credential. "Envelope, never the letter." Pure and unit-tested, so
+the safety rule is verifiable — there is no code path that reads a payload.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+_HOST_APP: list[tuple[str, str]] = [
+    ("api.notion.com", "notion"),
+    ("slack.com", "slack"),
+    ("gmail.googleapis.com", "gmail"),
+    ("api.xero.com", "xero"),
+    ("identity.xero.com", "xero"),
+    ("www.googleapis.com", "google"),
+    ("googleapis.com", "google"),
+    ("api.anthropic.com", "ai"),
+    ("api.openai.com", "ai"),
+    ("api.mistral.ai", "ai"),
+    ("generativelanguage.googleapis.com", "ai"),
+]
+
+
+def app_for_host(host: Optional[str], path: str = "") -> Optional[str]:
+    """The app slug for a destination host, or None if we don't recognise it."""
+    if not host:
+        return None
+    host = host.lower().strip(".")
+    app = None
+    for suffix, slug in _HOST_APP:
+        if host == suffix or host.endswith("." + suffix):
+            app = slug
+            break
+    if app is None:
+        return None
+    if app == "google":
+        p = path.lower()
+        if "/drive/" in p or p.startswith("/upload/drive"):
+            return "drive"
+        if "/gmail/" in p:
+            return "gmail"
+        if "/calendar/" in p:
+            return "calendar"
+        return "google"
+    return app
+
+
+def object_for(app: str, method: str, path: str) -> Optional[str]:
+    """A short operation label taken from the PATH only. Never reads the body."""
+    segs = [s for s in path.strip("/").split("/") if s]
+    if not segs:
+        return None
+    if app == "slack":
+        for s in segs:
+            if "." in s and s not in ("api",):
+                return s
+        return None
+    if app == "notion":
+        kinds = {"databases", "pages", "blocks", "users", "comments", "search", "data_sources"}
+        for s in segs:
+            if s in kinds:
+                return s
+        return None
+    if app in ("gmail", "google", "calendar"):
+        tail = [s for s in segs if s not in ("v1", "v3", "gmail", "users", "me")]
+        if tail:
+            return ".".join(tail[-2:]) if len(tail) >= 2 else tail[-1]
+        return None
+    if app == "drive":
+        for s in segs:
+            if s == "files":
+                return "files"
+        return None
+    if app == "xero":
+        tail = [s for s in segs if s not in ("api.xro", "2.0", "connections")]
+        return tail[-1] if tail else None
+    if app == "ai":
+        tail = [s for s in segs if s != "v1"]
+        if tail:
+            return ".".join(tail[-2:]) if len(tail) >= 2 else tail[-1]
+        return None
+    return None

bollard_ai-0.3.0/bollard/_bootstrap/sitecustomize.py

@@ -0,0 +1,32 @@
+"""Auto-start shim for the shared-codebase install (`bollard watch --key ... -- cmd`).
+
+Python imports a module named `sitecustomize` automatically at interpreter start-up
+if one is importable. The `bollard watch` CLI puts this directory on PYTHONPATH for
+the child process, so the agent starts up under Bollard without a code change.
+
+If the child already had its own `sitecustomize` elsewhere on the path, we run that
+one too (by file, without touching sys.modules), so we never disable someone else's
+startup hook.
+"""
+import os
+import sys
+
+try:  # pragma: no cover - environment dependent
+    _here = os.path.abspath(os.path.dirname(__file__))
+    for _dir in sys.path:
+        try:
+            _cand = os.path.join(_dir, "sitecustomize.py")
+            if os.path.abspath(_dir) != _here and os.path.isfile(_cand):
+                with open(_cand, "r", encoding="utf-8") as _f:
+                    exec(compile(_f.read(), _cand, "exec"), {"__name__": "sitecustomize", "__file__": _cand})
+                break
+        except Exception:
+            pass
+except Exception:
+    pass
+
+try:  # pragma: no cover - exercised via the CLI, not unit tests
+    import bollard
+    bollard.start()
+except Exception:
+    pass

bollard_ai-0.3.0/bollard/_context.py

@@ -0,0 +1,36 @@
+"""Which agent is acting right now.
+
+In a shared codebase, many agents run in the same process, so the package can't tell
+them apart just by watching calls. The library marks each agent's run:
+
+    with bollard.agent("sales-follow-up", token="boll_agt_..."):
+        run_the_agent()
+
+Every call made inside that block is attributed to (and, if the app is protected,
+enforced as) that agent. Outside any marker, the package falls back to the
+process-level identity passed to `start()`.
+"""
+from __future__ import annotations
+
+import contextvars
+from contextlib import contextmanager
+from typing import Iterator, Optional, Tuple
+
+# (name, token) for the agent currently acting on this call path, or None.
+_current: "contextvars.ContextVar[Optional[Tuple[Optional[str], Optional[str]]]]" = \
+    contextvars.ContextVar("bollard_agent", default=None)
+
+
+def current() -> Optional[Tuple[Optional[str], Optional[str]]]:
+    return _current.get()
+
+
+@contextmanager
+def agent(name: str, token: Optional[str] = None) -> Iterator[None]:
+    """Mark the enclosed work as done by `name`. Pass `token` (the agent's identity)
+    to make it enforceable. Nestable and safe across threads/async tasks."""
+    reset = _current.set((name, token))
+    try:
+        yield
+    finally:
+        _current.reset(reset)

bollard_ai-0.3.0/bollard/_patch.py

@@ -0,0 +1,184 @@
+"""HTTP interception — watch always, enforce when told to, per acting agent.
+
+For every outbound call we read only the method + URL (envelope), work out *which agent
+is acting* (a `bollard.agent(...)` marker if one is set, otherwise the process-level
+identity), report it (watch), and then:
+
+  * if the app is **watched** (the default): let the call go straight through, untouched.
+  * if the app is **enforced for this agent** (Bollard's policy says so) AND this agent
+    has an identity token: rewrite the call to go through Bollard's checkpoint (the
+    gateway) instead of straight to the app, so Bollard can allow or block it against
+    that agent's permissions.
+
+Two hard safety rules:
+  1. If anything in our wrapper raises, we fall through to the ORIGINAL call — the watcher
+     can never break what the agent was going to do.
+  2. We only ever re-route when the policy positively says "enforce" for the acting agent.
+     Absent/again-unsure/unidentified agent = watch = untouched. We never enforce on a
+     guessed identity.
+"""
+from __future__ import annotations
+
+from typing import Optional, Tuple
+from urllib.parse import urlsplit
+
+from ._apps import app_for_host, object_for
+from ._context import current
+from ._policy import Policy
+from ._reporter import Reporter
+
+_installed = False
+_originals: dict = {}
+
+
+def _acting(default_agent: Optional[str], default_token: Optional[str]) -> Tuple[Optional[str], Optional[str]]:
+    """Who is acting on this call: the marked agent if inside a `bollard.agent(...)`
+    block, else the process-level identity. A marker with no token is watch-only for
+    that agent (we won't enforce it under someone else's identity)."""
+    ctx = current()
+    if ctx is not None:
+        name, token = ctx
+        return (name or default_agent), token
+    return default_agent, default_token
+
+
+def _report(reporter: Reporter, app: str, method: str, path: str, agent: Optional[str]) -> None:
+    try:
+        reporter.record(app=app, object=object_for(app, method, path), method=method, agent=agent)
+    except Exception:
+        pass
+
+
+def _gateway_url(gateway_base: str, app: str, path: str, strip_prefix: str, query: str) -> str:
+    tail = path
+    if strip_prefix and tail.startswith(strip_prefix):
+        tail = tail[len(strip_prefix):]
+    if not tail.startswith("/"):
+        tail = "/" + tail
+    url = f"{gateway_base}/gw/{app}{tail}"
+    return url + ("?" + query if query else "")
+
+
+def install(reporter: Reporter, policy: Policy,
+            default_agent: Optional[str], default_token: Optional[str]) -> None:
+    global _installed
+    if _installed:
+        return
+    _installed = True
+    _patch_httpx(reporter, policy, default_agent, default_token)
+    _patch_requests(reporter, policy, default_agent, default_token)
+
+
+def uninstall() -> None:
+    global _installed
+    if not _installed:
+        return
+    for (owner, name), original in _originals.items():
+        try:
+            setattr(owner, name, original)
+        except Exception:
+            pass
+    _originals.clear()
+    _installed = False
+
+
+def _enforced_app(policy: Policy, token: Optional[str], host: Optional[str], path: str):
+    """Return (app, rule) if this call should be enforced for the acting agent, else
+    (app, None). Registers the agent's token so its policy gets fetched."""
+    app = app_for_host(host, path)
+    if not app:
+        return None, None
+    if not token:
+        return app, None
+    policy.ensure(token)
+    rule = policy.rule_for(app, token)
+    return app, (rule if rule.mode == "enforce" else None)
+
+
+def _patch_httpx(reporter: Reporter, policy: Policy,
+                 default_agent: Optional[str], default_token: Optional[str]) -> None:
+    try:
+        import httpx
+    except Exception:
+        return
+
+    def reroute_request(request):
+        """Build a new httpx.Request pointed at the gateway, or None to leave as-is."""
+        try:
+            agent, token = _acting(default_agent, default_token)
+            url = request.url
+            app, rule = _enforced_app(policy, token, url.host, url.path)
+            if app:
+                _report(reporter, app, request.method, url.path, agent)
+            if not (app and rule and token):
+                return None
+            new_url = _gateway_url(policy.gateway_base, app, url.path, rule.strip_prefix,
+                                   url.query.decode() if isinstance(url.query, bytes) else (url.query or ""))
+            headers = [(k, v) for k, v in request.headers.raw
+                       if k.lower() not in (b"authorization", b"host", b"content-length")]
+            headers.append((b"authorization", ("Bearer " + token).encode()))  # type: ignore[arg-type]
+            return httpx.Request(request.method, new_url, headers=headers, content=request.content)
+        except Exception:
+            return None  # fail-open: never break the call
+
+    def wrap(cls, is_async: bool):
+        original = cls.send
+        _originals[(cls, "send")] = original
+        if is_async:
+            async def send(self, request, *args, **kwargs):
+                new = None
+                try:
+                    new = reroute_request(request)
+                except Exception:
+                    new = None
+                return await original(self, new or request, *args, **kwargs)
+        else:
+            def send(self, request, *args, **kwargs):
+                new = None
+                try:
+                    new = reroute_request(request)
+                except Exception:
+                    new = None
+                return original(self, new or request, *args, **kwargs)
+        try:
+            cls.send = send
+        except Exception:
+            pass
+
+    wrap(httpx.Client, is_async=False)
+    wrap(httpx.AsyncClient, is_async=True)
+
+
+def _patch_requests(reporter: Reporter, policy: Policy,
+                    default_agent: Optional[str], default_token: Optional[str]) -> None:
+    try:
+        import requests
+    except Exception:
+        return
+
+    session = requests.sessions.Session
+    original = session.request
+    _originals[(session, "request")] = original
+
+    def request(self, method, url, *args, **kwargs):
+        try:
+            agent, token = _acting(default_agent, default_token)
+            parts = urlsplit(url)
+            app, rule = _enforced_app(policy, token, parts.hostname, parts.path)
+            if app:
+                _report(reporter, app, str(method).upper(), parts.path, agent)
+            if app and rule and token:
+                new_url = _gateway_url(policy.gateway_base, app, parts.path, rule.strip_prefix, parts.query)
+                headers = dict(kwargs.get("headers") or {})
+                headers = {k: v for k, v in headers.items() if k.lower() not in ("authorization", "host", "content-length")}
+                headers["Authorization"] = "Bearer " + token
+                kwargs["headers"] = headers
+                url = new_url
+        except Exception:
+            pass  # fail-open
+        return original(self, method, url, *args, **kwargs)
+
+    try:
+        session.request = request
+    except Exception:
+        pass

bollard_ai-0.3.0/bollard/_policy.py

@@ -0,0 +1,126 @@
+"""Enforcement policy — which apps are protected, *for a given agent*.
+
+Protection is per-agent-per-app: "the sales-follow-up agent is protected in Notion"
+is a different fact from "the research agent is protected in Notion". So the policy is
+keyed by the agent's own identity token: the package asks Bollard, for each agent
+identity it sees act, "which apps should I route through you for this agent?"
+
+  * The process-level agent (passed to `start(agent_token=...)`) is fetched up front,
+    so its enforcement is live from the first call.
+  * Agents marked mid-run with `bollard.agent(name, token=...)` are fetched lazily the
+    first time they act, then refreshed on the same cycle.
+
+Safety rule: if we can't reach Bollard, or anything looks off, we DEFAULT TO WATCH.
+We never start blocking an agent's calls off the back of a policy we couldn't confirm —
+enforcement only kicks in when Bollard positively tells us an app is protected for that
+agent. An agent we've never managed to fetch a policy for stays watch-only.
+"""
+from __future__ import annotations
+
+import json
+import threading
+import urllib.request
+from typing import Dict, Optional
+
+_TIMEOUT = 4.0
+_REFRESH_SECONDS = 60.0
+
+
+class AppRule:
+    __slots__ = ("mode", "strip_prefix")
+
+    def __init__(self, mode: str, strip_prefix: str) -> None:
+        self.mode = mode                    # "watch" | "enforce"
+        self.strip_prefix = strip_prefix    # path prefix the gateway already re-adds (e.g. "/v1")
+
+
+_WATCH = AppRule("watch", "")
+
+
+class Policy:
+    def __init__(self, *, policy_url: str, gateway_base: str) -> None:
+        self._url = policy_url
+        self._gateway_base = gateway_base.rstrip("/")
+        self._rules: Dict[str, Dict[str, AppRule]] = {}   # agent_token -> {app: AppRule}
+        self._pending: set = set()                        # tokens awaiting a first fetch
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._wake = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+
+    @property
+    def gateway_base(self) -> str:
+        return self._gateway_base
+
+    def ensure(self, token: Optional[str]) -> None:
+        """Register an agent token so its policy gets fetched (lazily, off the hot path).
+        Cheap and idempotent — safe to call on every request."""
+        if not token:
+            return
+        with self._lock:
+            if token in self._rules or token in self._pending:
+                return
+            self._pending.add(token)
+        self._wake.set()
+
+    def rule_for(self, app: str, token: Optional[str]) -> AppRule:
+        """The rule for this app *for this agent*. Unknown agent/app = watch (safe)."""
+        if not token:
+            return _WATCH
+        with self._lock:
+            return self._rules.get(token, {}).get(app, _WATCH)
+
+    def prime(self, token: Optional[str]) -> None:
+        """Fetch one agent's policy synchronously (used for the process-level agent so its
+        enforcement is live before the first call)."""
+        if token:
+            self._fetch(token)
+
+    def start(self) -> None:
+        self._thread = threading.Thread(target=self._loop, name="bollard-policy", daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        self._wake.set()
+
+    def _loop(self) -> None:
+        while not self._stop.is_set():
+            # 1) fetch any newly-seen agents promptly
+            with self._lock:
+                pending = list(self._pending)
+                self._pending.clear()
+            for token in pending:
+                if self._stop.is_set():
+                    return
+                self._fetch(token)
+            # 2) wait for the refresh interval, but wake early if a new agent appears
+            if self._wake.wait(_REFRESH_SECONDS):
+                self._wake.clear()
+                continue
+            # 3) interval elapsed with nothing new → refresh everyone we know
+            with self._lock:
+                known = list(self._rules.keys())
+            for token in known:
+                if self._stop.is_set():
+                    return
+                self._fetch(token)
+
+    def _fetch(self, token: str) -> None:
+        try:
+            req = urllib.request.Request(
+                self._url, headers={"User-Agent": "bollard", "Authorization": "Bearer " + token})
+            with urllib.request.urlopen(req, timeout=_TIMEOUT) as r:
+                data = json.loads(r.read().decode())
+            gateway = (data.get("gateway_base") or self._gateway_base).rstrip("/")
+            rules: Dict[str, AppRule] = {}
+            for app, spec in (data.get("apps") or {}).items():
+                if isinstance(spec, dict) and spec.get("mode") == "enforce":
+                    rules[app] = AppRule("enforce", str(spec.get("strip_prefix") or ""))
+            with self._lock:
+                self._gateway_base = gateway
+                self._rules[token] = rules
+                self._pending.discard(token)
+        except Exception:
+            # Unreachable / malformed → leave this agent as-is (unknown = watch).
+            pass

bollard_ai-0.3.0/bollard/_reporter.py

@@ -0,0 +1,94 @@
+"""Background reporter — ships watch signals to Bollard without making the agent wait.
+
+The hot path only does `reporter.record(...)`, which drops a small tuple on a queue
+and returns. A daemon thread drains it, batches, and POSTs on its own time with a
+short timeout. Unreachable Bollard = signals dropped, never retried forever, never
+surfaced. Envelope facts only — app slug, operation label, method, agent hint.
+"""
+from __future__ import annotations
+
+import atexit
+import json
+import queue
+import threading
+import time
+import urllib.error
+import urllib.request
+from typing import Optional
+
+_MAX_QUEUE = 1000
+_BATCH = 50
+_FLUSH_SECONDS = 2.0
+_TIMEOUT = 3.0
+
+
+class Reporter:
+    def __init__(self, *, key: str, signal_url: str, agent: Optional[str]) -> None:
+        self._key = key
+        self._url = signal_url
+        self._agent = agent
+        self._q: "queue.Queue[dict]" = queue.Queue(maxsize=_MAX_QUEUE)
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, name="bollard", daemon=True)
+        self._started = False
+        self._seen: dict[tuple, int] = {}
+
+    def start(self) -> None:
+        if self._started:
+            return
+        self._started = True
+        self._thread.start()
+        atexit.register(self.flush_and_stop)
+
+    def record(self, *, app: str, object: Optional[str], method: str,
+               agent: Optional[str] = None) -> None:
+        try:
+            eff_agent = agent or self._agent
+            k = (eff_agent, app, object, method)
+            n = self._seen.get(k, 0)
+            self._seen[k] = n + 1
+            if n >= 5:
+                return
+            self._q.put_nowait({"app": app, "object": object, "method": method,
+                                "agent": eff_agent, "ts": time.time()})
+        except Exception:
+            pass
+
+    def _run(self) -> None:
+        batch: list[dict] = []
+        last = time.time()
+        while not self._stop.is_set():
+            timeout = max(0.05, _FLUSH_SECONDS - (time.time() - last))
+            try:
+                batch.append(self._q.get(timeout=timeout))
+            except queue.Empty:
+                pass
+            if batch and (len(batch) >= _BATCH or (time.time() - last) >= _FLUSH_SECONDS):
+                self._send(batch)
+                batch = []
+                last = time.time()
+        while True:
+            try:
+                batch.append(self._q.get_nowait())
+            except queue.Empty:
+                break
+        if batch:
+            self._send(batch)
+
+    def _send(self, batch: list[dict]) -> None:
+        payload = {"key": self._key, "agent": self._agent, "signals": batch}
+        try:
+            req = urllib.request.Request(
+                self._url, data=json.dumps(payload).encode(), method="POST",
+                headers={"Content-Type": "application/json", "User-Agent": "bollard"},
+            )
+            urllib.request.urlopen(req, timeout=_TIMEOUT).close()
+        except (urllib.error.URLError, OSError, ValueError):
+            pass
+        except Exception:
+            pass
+
+    def flush_and_stop(self) -> None:
+        self._stop.set()
+        if self._started and self._thread.is_alive():
+            self._thread.join(timeout=_TIMEOUT + 1)

bollard_ai-0.3.0/bollard/cli.py

@@ -0,0 +1,78 @@
+"""`bollard` command-line entry point.
+
+    bollard watch --key BWATCH-... -- python my_agents.py
+
+runs your program with Bollard switched on, without editing a line of its code — the
+shared-codebase path. It sets a few environment variables and puts a tiny auto-start
+shim on the child's import path (see _bootstrap/sitecustomize.py). Add --agent-token
+to make an agent enforceable; without it, it's watch-only.
+
+With no command it prints the one-line instructions instead of doing anything.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import Optional
+
+
+def _bootstrap_dir() -> str:
+    return os.path.join(os.path.dirname(__file__), "_bootstrap")
+
+
+def _run_child(args, cmd: list[str]) -> int:
+    env = dict(os.environ)
+    env["BOLLARD_KEY"] = args.key
+    if args.agent:
+        env["BOLLARD_AGENT"] = args.agent
+    if args.agent_token:
+        env["BOLLARD_AGENT_TOKEN"] = args.agent_token
+    if args.endpoint:
+        env["BOLLARD_ENDPOINT"] = args.endpoint
+    boot = _bootstrap_dir()
+    existing = env.get("PYTHONPATH", "")
+    env["PYTHONPATH"] = boot + (os.pathsep + existing if existing else "")
+    import subprocess
+    try:
+        return subprocess.call(cmd, env=env)
+    except FileNotFoundError:
+        print(f"bollard: couldn't run '{cmd[0]}' — is it installed and on your PATH?", file=sys.stderr)
+        return 127
+
+
+def _print_instructions(key: str) -> None:
+    print(
+        "Bollard is ready.\n\n"
+        "Run your agents through this command so Bollard can see which apps they use:\n\n"
+        f"    bollard watch --key {key} -- python your_agent.py\n\n"
+        "It only watches — it can't slow your agents down or change what they do.\n\n"
+        "Prefer not to wrap the command? Add one line where each agent starts up:\n\n"
+        f'    import bollard; bollard.start(key="{key}")\n'
+    )
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = argparse.ArgumentParser(prog="bollard", description="Bollard — see, then govern, your AI agents")
+    sub = parser.add_subparsers(dest="command")
+    watch = sub.add_parser("watch", help="run your agents through Bollard")
+    watch.add_argument("--key", required=True, help="your workspace key (BWATCH-...)")
+    watch.add_argument("--agent", default=None, help="optional name for this agent")
+    watch.add_argument("--agent-token", dest="agent_token", default=None,
+                       help="this agent's identity (boll_agt_...) — needed to enforce; watch-only without it")
+    watch.add_argument("--endpoint", default=None, help="override Bollard's base address")
+    watch.add_argument("cmd", nargs=argparse.REMAINDER, help="the command to run, after '--'")
+
+    args = parser.parse_args(argv)
+    if args.command != "watch":
+        parser.print_help()
+        return 0
+    cmd = args.cmd[1:] if args.cmd and args.cmd[0] == "--" else args.cmd
+    if not cmd:
+        _print_instructions(args.key)
+        return 0
+    return _run_child(args, cmd)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bollard_ai-0.3.0/bollard_ai.egg-info/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: bollard-ai
+Version: 0.3.0
+Summary: See, then govern, your AI agents — watch which apps they use, and enforce what they're allowed to do.
+Author: Bollard AI
+License: Proprietary
+Project-URL: Homepage, https://bollardai.com
+Keywords: bollard,ai agents,governance,observability,security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# bollard
+
+The one line that lets Bollard **see, then govern** your AI agents.
+
+Add it where your agents start up. By default it's **watch-only** — it notes which
+apps your agents use (Notion, Slack, Gmail, Xero, Drive, paid AI models), never what
+they read or write, and reports it to Bollard. When you protect an app in Bollard, the
+same install starts routing *that app's* calls through Bollard so each agent can only
+do what you allow — no code change. Every other app stays watch-only.
+
+Three promises, enforced in code:
+
+- **It can't break your agents.** Watch-only observes and, if anything goes wrong,
+  falls straight through to the real call. Enforcement is opt-in, per app, reversible.
+- **It can't slow them down.** It reports in the background on its own thread.
+- **It never sees your data or code.** It reads only the *envelope* of each call — the
+  destination and operation name. There is no code path that reads a request or
+  response body (see `bollard/_apps.py`).
+
+## Install
+
+```bash
+pip install bollard-ai
+```
+
+## Use it
+
+**One shared codebase** — wrap the command, no code change:
+
+```bash
+bollard watch --key BWATCH-XXXX-XXXX-XXXX -- python your_agents.py
+```
+
+**Separate projects** — add one line where each agent starts up:
+
+```python
+import bollard
+bollard.start(key="BWATCH-XXXX-XXXX-XXXX", agent="sales-follow-up")
+```
+
+## Enforcement (opt-in)
+
+Watching needs only your workspace key. To let Bollard *enforce* an agent (once you've
+protected an app in the dashboard), give that agent its own identity:
+
+```python
+bollard.start(key="BWATCH-...", agent="sales-follow-up", agent_token="boll_agt_...")
+```
+
+With an `agent_token`, calls to any **protected** app are routed through Bollard, which
+allows or blocks them against that agent's permissions. Apps you haven't protected stay
+watch-only. No `agent_token` → always watch-only. If Bollard can't be reached to confirm
+the policy, the agent stays watch-only — it never starts blocking off an unconfirmed rule.
+
+## Configuration
+
+`start()` reads these when the arguments are omitted:
+
+| Variable | Meaning |
+|---|---|
+| `BOLLARD_KEY` | your workspace key (`BWATCH-...`) |
+| `BOLLARD_AGENT` | optional name for this agent |
+| `BOLLARD_AGENT_TOKEN` | this agent's identity (`boll_agt_...`), for enforcement |
+| `BOLLARD_ENDPOINT` | override Bollard's base address (self-hosting / testing) |

bollard_ai-0.3.0/bollard_ai.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+bollard/__init__.py
+bollard/_apps.py
+bollard/_context.py
+bollard/_patch.py
+bollard/_policy.py
+bollard/_reporter.py
+bollard/cli.py
+bollard/_bootstrap/sitecustomize.py
+bollard_ai.egg-info/PKG-INFO
+bollard_ai.egg-info/SOURCES.txt
+bollard_ai.egg-info/dependency_links.txt
+bollard_ai.egg-info/entry_points.txt
+bollard_ai.egg-info/top_level.txt
+tests/test_bollard.py

bollard_ai-0.3.0/bollard_ai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bollard_ai-0.3.0/bollard_ai.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bollard = bollard.cli:main

bollard_ai-0.3.0/bollard_ai.egg-info/top_level.txt

@@ -0,0 +1 @@
+bollard

bollard_ai-0.3.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+# Distribution name is "bollard-ai" (the plain "bollard" name is taken on PyPI). The
+# import name stays `bollard` and the CLI command stays `bollard` — only the
+# `pip install` line differs: `pip install bollard-ai`, then `import bollard`.
+[project]
+name = "bollard-ai"
+version = "0.3.0"
+description = "See, then govern, your AI agents — watch which apps they use, and enforce what they're allowed to do."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+authors = [{ name = "Bollard AI" }]
+keywords = ["bollard", "ai agents", "governance", "observability", "security"]
+# No runtime dependencies: it hooks httpx/requests only if the agent already uses
+# them, and talks to Bollard over the standard library.
+dependencies = []
+
+[project.urls]
+Homepage = "https://bollardai.com"
+
+[project.scripts]
+bollard = "bollard.cli:main"
+
+[tool.setuptools]
+packages = ["bollard"]
+
+[tool.setuptools.package-data]
+bollard = ["_bootstrap/sitecustomize.py"]

bollard_ai-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bollard_ai-0.3.0/tests/test_bollard.py

@@ -0,0 +1,187 @@
+"""Tests for the unified bollard package.
+
+Run: `python tests/test_bollard.py` (or pytest) from sdk/bollard.
+
+Covers the envelope reader, the watch path (captures a signal, reads no body, leaves
+the call untouched), the enforce path (a protected app is rerouted through the gateway
+with the agent's identity; an unprotected app is left alone), and the per-agent marker
+(`bollard.agent(...)`) that attributes and enforces the right agent when several share
+one process.
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from bollard._apps import app_for_host, object_for  # noqa: E402
+from bollard._patch import _gateway_url  # noqa: E402
+from bollard._policy import AppRule, Policy  # noqa: E402
+
+
+class FakeReporter:
+    def __init__(self):
+        self.seen = []
+
+    def record(self, *, app, object, method, agent=None):
+        self.seen.append((app, object, method, agent))
+
+
+def _watch_policy():
+    return Policy(policy_url="", gateway_base="https://api.bollardai.com")
+
+
+def _enforce_policy(token, **rules):
+    """A policy that enforces `rules` (app -> strip_prefix) for one agent token."""
+    p = _watch_policy()
+    p._rules = {token: {app: AppRule("enforce", strip) for app, strip in rules.items()}}
+    return p
+
+
+# --- envelope reader ---------------------------------------------------------
+
+def test_host_and_object():
+    assert app_for_host("api.notion.com", "/v1/pages/x") == "notion"
+    assert app_for_host("slack.com", "/api/chat.postMessage") == "slack"
+    assert app_for_host("example.com", "/") is None
+    assert object_for("slack", "POST", "/api/chat.postMessage") == "chat.postMessage"
+    assert object_for("notion", "GET", "/v1/databases/x/query") == "databases"
+
+
+def test_gateway_url_strips_service_prefix():
+    assert _gateway_url("https://api.bollardai.com", "notion", "/v1/pages/abc", "/v1", "") \
+        == "https://api.bollardai.com/gw/notion/pages/abc"
+    assert _gateway_url("https://api.bollardai.com", "slack", "/api/chat.postMessage", "/api", "a=1") \
+        == "https://api.bollardai.com/gw/slack/chat.postMessage?a=1"
+
+
+# --- watch path (default) ----------------------------------------------------
+
+def test_watch_captures_and_never_reroutes_or_reads_body():
+    import httpx
+    from bollard import _patch
+
+    reads = {"n": 0}
+    captured = []
+
+    class Spy(httpx.Request):
+        @property
+        def content(self):  # pragma: no cover - fires only if we misbehave
+            reads["n"] += 1
+            return super().content
+
+    def handler(request):
+        captured.append(str(request.url))
+        return httpx.Response(200, json={"ok": True})
+
+    rep = FakeReporter()
+    _patch.install(rep, _watch_policy(), None, None)  # no identity → watch-only
+    try:
+        with httpx.Client(transport=httpx.MockTransport(handler)) as c:
+            resp = c.send(Spy("POST", "https://api.notion.com/v1/pages/abc", json={"secret": "x"}))
+    finally:
+        _patch.uninstall()
+
+    assert resp.status_code == 200
+    assert ("notion", "pages", "POST", None) in rep.seen        # watched
+    assert captured == ["https://api.notion.com/v1/pages/abc"]  # went straight to Notion
+    assert reads["n"] == 0                                       # body never read
+
+
+# --- enforce path (protected app) --------------------------------------------
+
+def test_enforce_reroutes_protected_app_through_gateway():
+    import httpx
+    from bollard import _patch
+
+    seen = []
+
+    def handler(request):
+        seen.append((str(request.url), request.headers.get("authorization")))
+        return httpx.Response(200, json={"ok": True})
+
+    policy = _enforce_policy("boll_agt_TEST", notion="/v1")   # notion protected; slack not
+    _patch.install(FakeReporter(), policy, None, "boll_agt_TEST")
+    try:
+        with httpx.Client(transport=httpx.MockTransport(handler)) as c:
+            c.send(httpx.Request("GET", "https://api.notion.com/v1/pages/abc"))     # protected → reroute
+            c.send(httpx.Request("POST", "https://slack.com/api/chat.postMessage"))  # not protected → direct
+    finally:
+        _patch.uninstall()
+
+    assert seen[0] == ("https://api.bollardai.com/gw/notion/pages/abc", "Bearer boll_agt_TEST")
+    assert seen[1][0] == "https://slack.com/api/chat.postMessage"   # slack untouched
+    assert seen[1][1] is None
+
+
+def test_enforce_needs_a_token():
+    import httpx
+    from bollard import _patch
+
+    seen = []
+    policy = _enforce_policy("boll_agt_TEST", notion="/v1")
+    _patch.install(FakeReporter(), policy, None, None)  # protected app but no identity → watch
+    try:
+        with httpx.Client(transport=httpx.MockTransport(lambda r: (seen.append(str(r.url)) or httpx.Response(200)))) as c:
+            c.send(httpx.Request("GET", "https://api.notion.com/v1/pages/abc"))
+    finally:
+        _patch.uninstall()
+    assert seen == ["https://api.notion.com/v1/pages/abc"]   # stayed direct (watch-only)
+
+
+# --- per-agent marker (shared process) ---------------------------------------
+
+def test_agent_marker_enforces_the_right_agent():
+    """Two agents in one process. Notion is protected for 'A' only. Each agent's calls
+    are routed by *its* identity, not the process's."""
+    import httpx
+    from bollard import _patch, agent
+
+    seen = []
+
+    def handler(request):
+        seen.append((str(request.url), request.headers.get("authorization")))
+        return httpx.Response(200, json={"ok": True})
+
+    policy = _watch_policy()
+    policy._rules = {"boll_agt_A": {"notion": AppRule("enforce", "/v1")}}  # A protected; B not
+    _patch.install(FakeReporter(), policy, None, None)  # no process-level identity
+    try:
+        with httpx.Client(transport=httpx.MockTransport(handler)) as c:
+            with agent("sales", token="boll_agt_A"):
+                c.send(httpx.Request("GET", "https://api.notion.com/v1/pages/abc"))   # A → reroute
+            with agent("research", token="boll_agt_B"):
+                c.send(httpx.Request("GET", "https://api.notion.com/v1/pages/xyz"))   # B → direct
+            c.send(httpx.Request("GET", "https://api.notion.com/v1/pages/zzz"))       # unmarked → direct
+    finally:
+        _patch.uninstall()
+
+    assert seen[0] == ("https://api.bollardai.com/gw/notion/pages/abc", "Bearer boll_agt_A")
+    assert seen[1] == ("https://api.notion.com/v1/pages/xyz", None)
+    assert seen[2] == ("https://api.notion.com/v1/pages/zzz", None)
+
+
+def test_agent_marker_attributes_signals():
+    """The marker sets who a watched call is attributed to; outside it, the process default."""
+    import httpx
+    from bollard import _patch, agent
+
+    rep = FakeReporter()
+    _patch.install(rep, _watch_policy(), "proc-default", None)
+    try:
+        with httpx.Client(transport=httpx.MockTransport(lambda r: httpx.Response(200))) as c:
+            with agent("sales"):
+                c.send(httpx.Request("POST", "https://api.notion.com/v1/pages/abc"))
+            c.send(httpx.Request("POST", "https://slack.com/api/chat.postMessage"))
+    finally:
+        _patch.uninstall()
+
+    assert ("notion", "pages", "POST", "sales") in rep.seen                  # marked → 'sales'
+    assert ("slack", "chat.postMessage", "POST", "proc-default") in rep.seen  # unmarked → default
+
+
+if __name__ == "__main__":
+    fns = [v for k, v in sorted(globals().items()) if k.startswith("test_") and callable(v)]
+    for fn in fns:
+        fn()
+        print(f"ok  {fn.__name__}")
+    print(f"\n{len(fns)} passed")