feat(crewai,llamaindex): two-line adoption path + STH stamping

Ports the v0.2 distribution wedge from langchain-haldir to
crewai-haldir and llamaindex-haldir. Same HaldirSession contract
across all three Python frameworks — operators running multi-
framework deployments transfer the mental model verbatim.

crewai-haldir v0.1.0 → 0.2.0
llamaindex-haldir v0.1.0 → 0.2.0

Each package now ships:

  HaldirSession context manager — __enter__ mints a scoped Haldir
  session; __exit__ revokes it even on user-code exception (revoke
  failures are swallowed so they can't mask the user's exception).
  Reads HALDIR_API_KEY + HALDIR_BASE_URL from env via .for_agent(),
  matches the ergonomics every LangChain-adjacent integration uses.

  .stamp_sth(result) helper — fetches the tenant's current Signed
  Tree Head and attaches it to the framework's return value, with
  shape-aware dispatch: dict gets _haldir_sth key, an object with
  __dict__ gets it as an attribute (e.g. CrewAI's CrewOutput,
  LlamaIndex's AgentChatResponse), bare values get wrapped. STH
  fetch errors NEVER mutate the caller's output — we return the
  original unchanged so a flaky tree-head call can't break the
  run's happy path. Auditors pin the STH once, verify offline
  any time later that the run's audit entries are still in the
  log unchanged.

  Spend / audit / STH helpers on the session — spend_summary(),
  audit_trail(), current_sth() forward to the underlying SDK
  client scoped to the active session. Used for mid-run
  dashboards (e.g. "we've burned 62% of our $5 cap").

  Lazy framework import — GovernedTool (crewai) and
  govern_tool / GovernedTool (llamaindex) use a module-level
  __getattr__ so the package imports cleanly even before
  `pip install crewai` or `pip install llama-index-core`. This
  lets CI test the session layer without the heavy framework
  dependency chain; full test install only needed for the
  hard-enforcement tool tests.

tests/ (new):
  crewai-haldir: 11 tests covering mint+revoke, exception-path
  revoke, env vs explicit key, helpers forward correctly,
  stamp_sth shape dispatch (dict / object / bare), network-error
  invariance.
  llamaindex-haldir: 10 tests with the same matrix + a
  AgentChatResponse-style object-attachment test specifically
  because LlamaIndex's .chat() returns that shape.

examples/ (new):
  two_line_crew.py — end-to-end CrewAI ReAct flow with SerperDevTool,
  2-line Haldir adoption, STH stamp, spend summary.
  two_line_agent.py — end-to-end LlamaIndex ReActAgent flow with
  FunctionTool, same 2-line pattern.

READMEs rewritten for both: the two-line quickstart is the first
thing a reader sees; `What you get` table replaces the v0.1
scattered-feature-list; legacy create_session() noted as back-
compat only.

Main Haldir suite: 590 still green (zero regressions).

Together with langchain-haldir v0.2 (already shipped), Haldir is
now in three of the four major Python agent frameworks with the
same two-line adoption contract. Remaining: autogen-haldir (same
pattern, next tranche) and the Vercel AI SDK TS package.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Sterling Ivey

integrations/crewai-haldir/README.md

@@ -1,63 +1,59 @@
 # crewai-haldir
 
-Governance layer for CrewAI agents — audit trails, spend caps, secrets vault, and instant revocation.
+Cryptographic-audit + governance for CrewAI agents. Two lines of code.
 
-Wrap any CrewAI tool in Haldir's enforcement proxy so every tool call is scope-checked, cost-tracked, and logged to a tamper-evident audit trail.
+- **Audit trail** — every tool call logged to a SHA-256 hash-chained + RFC 6962 Merkle-covered audit log
+- **Scope enforcement** — denied tools abort with `HaldirPermissionError`
+- **Secrets vault** — scope-checked credential retrieval as `SecretStr`
+- **Tree-head stamping** — attach the current Signed Tree Head to the crew's output; pin for offline verification later
+- **Instant revocation** — any process can revoke a session mid-run; next tool call aborts
+- **Auto-lifecycle** — session minted on `with` entry, revoked on exit even if the crew raises
 
 ## Install
 
 ```bash
 pip install crewai-haldir
 ```
 
-You'll need a Haldir API key. Create one free at [haldir.xyz](https://haldir.xyz).
+Free Haldir API key at [haldir.xyz](https://haldir.xyz).
 
-## 30-second quickstart
+## Two-line quickstart
 
 ```python
 from crewai import Agent, Task, Crew
 from crewai_tools import SerperDevTool
-from crewai_haldir import create_session, GovernedTool
-
-# Create a scoped Haldir session with a $10 spend cap
-client, session_id = create_session(
-    api_key="hld_xxx",
-    agent_id="research-crew",
-    scopes=["read", "search", "spend"],
-    spend_limit=10.0,
-)
-
-# Wrap your tools so Haldir enforces permissions
-search = GovernedTool.wrap(
-    SerperDevTool(),
-    client=client,
-    session_id=session_id,
-    required_scope="search",
-    cost_usd=0.01,
-)
+from crewai_haldir import HaldirSession, GovernedTool   # ← line 1
+
+with HaldirSession.for_agent("research-crew",           # ← line 2
+                              scopes=["read", "search"],
+                              spend_limit=10.0) as haldir:
+    search = GovernedTool.wrap(
+        SerperDevTool(),
+        client=haldir.client,
+        session_id=haldir.session_id,
+        required_scope="search",
+        cost_usd=0.01,
+    )
+
+    researcher = Agent(role="Researcher", goal="...", tools=[search])
+    task = Task(description="...", expected_output="...", agent=researcher)
+    crew = Crew(agents=[researcher], tasks=[task])
+
+    result = haldir.stamp_sth(crew.kickoff())
+    # result["_haldir_sth"] or result._haldir_sth — pin it for
+    # offline verification any time later.
+```
 
-# Build your crew as usual — governance happens transparently
-researcher = Agent(
-    role="Senior Research Analyst",
-    goal="Find the most recent news on a topic",
-    backstory="A diligent researcher with attention to sources.",
-    tools=[search],
-)
+`HaldirSession.for_agent(...)` reads `HALDIR_API_KEY` + `HALDIR_BASE_URL` from the env. Session auto-revoked on scope exit, including on exception.
 
-task = Task(
-    description="Find the latest news about AI agent security incidents.",
-    expected_output="A bulleted list with sources.",
-    agent=researcher,
-)
-
-crew = Crew(agents=[researcher], tasks=[task])
-crew.kickoff()
-```
+## What you get
 
-Every tool call is now:
-- **Permission-checked** before execution (revoked or out-of-scope sessions raise `HaldirPermissionError`)
-- **Cost-tracked** against the session's `spend_limit`
-- **Logged** to Haldir's hash-chained audit trail with tool name, timestamp, and cost
+| Step | Haldir action |
+|---|---|
+| Session enter | Mints a scoped session with the spend cap |
+| GovernedTool `_run` | Checks scope; logs call with input/output/cost |
+| `haldir.stamp_sth(result)` | Fetches current STH and attaches to the result |
+| Session exit (any path) | Revokes the session |
 
 ## Secrets without leaking them to the model
 

integrations/crewai-haldir/crewai_haldir/__init__.py

@@ -30,14 +30,27 @@
     crew.kickoff()
 """
 
-from .session import create_session
-from .governed_tool import GovernedTool
+"""Exports. `GovernedTool` requires the `crewai` package to be
+installed; if the user hasn't installed it yet, `HaldirSession` +
+`HaldirSecrets` still work standalone. Lazy import keeps the package
+importable even before `pip install crewai` so the session-level
+surface is testable in CI without the heavy dep chain."""
+
+from .session import HaldirSession, create_session
 from .secrets import HaldirSecrets
 
 __all__ = [
+    "HaldirSession",
     "create_session",
     "GovernedTool",
     "HaldirSecrets",
 ]
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
+
+
+def __getattr__(name: str):
+    if name == "GovernedTool":
+        from .governed_tool import GovernedTool
+        return GovernedTool
+    raise AttributeError(f"module 'crewai_haldir' has no attribute {name!r}")

integrations/crewai-haldir/crewai_haldir/session.py

@@ -1,26 +1,196 @@
-"""Helper to create a Haldir session for a CrewAI run."""
+"""
+HaldirSession for CrewAI — context manager that auto-mints + auto-revokes.
+
+The two-line promise::
+
+    from crewai_haldir import HaldirSession
+
+    with HaldirSession.for_agent("research-crew",
+                                  scopes=["read", "search"],
+                                  spend_limit=10.0) as haldir:
+        # Use haldir.client + haldir.session_id to wrap your
+        # CrewAI tools with GovernedTool.wrap(...). Session is
+        # auto-revoked on scope exit, even on exception.
+        ...
+        # After crew.kickoff(), stamp the run's output with the
+        # current STH so an auditor can verify later:
+        #   result = haldir.stamp_sth(crew.kickoff())
+
+Why it exists:
+
+  CrewAI doesn't have a single BaseCallbackHandler primitive the way
+  LangChain does, so the integration lives at the TOOL level
+  (GovernedTool.wrap) and the SESSION level (this module). The
+  session handles lifecycle + ergonomics; GovernedTool handles the
+  per-call scope check + audit write.
+"""
 
 from __future__ import annotations
 
-from typing import Optional
+import os
+from types import TracebackType
+from typing import Any
 
 from sdk.client import HaldirClient
 
 
+class HaldirSession:
+    """Haldir session lifecycle scoped to a CrewAI run.
+
+    Usage::
+
+        with HaldirSession.for_agent("my-crew") as haldir:
+            search_tool = GovernedTool.wrap(
+                SerperDevTool(),
+                client=haldir.client,
+                session_id=haldir.session_id,
+                required_scope="search",
+                cost_usd=0.01,
+            )
+            crew = Crew(agents=[...], tasks=[...])
+            result = haldir.stamp_sth(crew.kickoff())
+
+    ``result`` now carries an `_haldir_sth` attribute (if it's a dict or
+    has ``__dict__``) with the tenant's current Signed Tree Head.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        agent_id: str,
+        scopes: list[str] | None = None,
+        ttl: int = 3600,
+        spend_limit: float | None = None,
+    ) -> None:
+        api_key  = api_key  or os.environ.get("HALDIR_API_KEY", "").strip()
+        base_url = base_url or os.environ.get(
+            "HALDIR_BASE_URL", "https://haldir.xyz",
+        )
+        if not api_key:
+            raise RuntimeError(
+                "HaldirSession requires an API key. Pass `api_key=...` "
+                "or set HALDIR_API_KEY in the environment."
+            )
+        self._agent_id    = agent_id
+        self._scopes      = scopes
+        self._ttl         = ttl
+        self._spend_limit = spend_limit
+        self.client = HaldirClient(api_key=api_key, base_url=base_url)
+        self.session_id: str | None = None
+
+    @classmethod
+    def for_agent(
+        cls,
+        agent_id: str,
+        *,
+        scopes: list[str] | None = None,
+        spend_limit: float | None = None,
+        **kwargs: Any,
+    ) -> "HaldirSession":
+        """Shortest entry point. Reads HALDIR_API_KEY + HALDIR_BASE_URL
+        from env."""
+        return cls(
+            agent_id=agent_id,
+            scopes=scopes,
+            spend_limit=spend_limit,
+            **kwargs,
+        )
+
+    # ── Context-manager protocol ────────────────────────────────────
+
+    def __enter__(self) -> "HaldirSession":
+        session = self.client.create_session(
+            self._agent_id,
+            scopes=self._scopes,
+            ttl=self._ttl,
+            spend_limit=self._spend_limit,
+        )
+        self.session_id = session["session_id"]
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        """Always revoke on scope exit, even on exception. A revoke
+        failure MUST NOT mask the user's exception."""
+        if self.session_id is None:
+            return
+        try:
+            self.client.revoke_session(self.session_id)
+        except Exception:
+            pass
+        finally:
+            self.session_id = None
+
+    # ── Ergonomic helpers ────────────────────────────────────────────
+
+    def spend_summary(self) -> dict[str, Any]:
+        """Current spend on this session."""
+        if not self.session_id:
+            return {"total_usd": 0.0, "action_count": 0}
+        return self.client.get_spend(session_id=self.session_id)
+
+    def audit_trail(self, limit: int = 100) -> dict[str, Any]:
+        """Every audit entry written under this session."""
+        if not self.session_id:
+            return {"entries": [], "count": 0}
+        return self.client.get_audit_trail(
+            session_id=self.session_id, limit=limit,
+        )
+
+    def current_sth(self) -> dict[str, Any]:
+        """Fetch the tenant's current Signed Tree Head. Pin it for
+        later offline verification."""
+        return self.client.get_tree_head()
+
+    def stamp_sth(self, result: Any) -> Any:
+        """Attach the current STH to a CrewAI run result so an auditor
+        can pin it.
+
+        Behaviour depends on the shape `crew.kickoff()` returned:
+
+          - dict: writes result["_haldir_sth"] = sth
+          - object with __dict__: sets result._haldir_sth = sth
+          - anything else: wraps into a new dict
+              {"output": result, "_haldir_sth": sth}
+
+        Returns the (possibly-wrapped) result unchanged in identity
+        whenever possible. Network errors fetching the STH never
+        break the caller's output path — we return the original
+        result unmodified if the fetch fails."""
+        try:
+            sth = self.current_sth()
+        except Exception:
+            return result
+        if isinstance(result, dict):
+            result["_haldir_sth"] = sth
+            return result
+        if hasattr(result, "__dict__"):
+            try:
+                setattr(result, "_haldir_sth", sth)
+                return result
+            except Exception:
+                pass
+        return {"output": result, "_haldir_sth": sth}
+
+
+# ── Legacy helper ─────────────────────────────────────────────────
+
 def create_session(
     api_key: str,
     agent_id: str,
-    scopes: Optional[list[str]] = None,
-    ttl: Optional[int] = None,
-    spend_limit: Optional[float] = None,
+    scopes: list[str] | None = None,
+    ttl: int | None = None,
+    spend_limit: float | None = None,
     base_url: str = "https://haldir.xyz",
 ) -> tuple[HaldirClient, str]:
-    """Create a Haldir client and a scoped session in one step.
-
-    Returns:
-        (client, session_id) — pass both into GovernedTool.wrap and
-        HaldirSecrets so they can enforce and log against the same session.
-    """
+    """Legacy helper — returns (client, session_id). New code should
+    prefer HaldirSession. Kept for back-compat with v0.1 callers."""
     client = HaldirClient(api_key=api_key, base_url=base_url)
     session = client.create_session(
         agent_id=agent_id,