lodestar-langgraph 0.3.0__tar.gz

lodestar_langgraph-0.3.0/.gitignore

@@ -0,0 +1,28 @@
+node_modules/
+.lodestar/
+dist/
+build/
+_site/
+*.tsbuildinfo
+
+# Claude Code / agent-tool per-machine settings — keep `.claude/` tracked
+# for the agent guidance and slash commands, but never commit the
+# per-machine bash-permission allowlists.
+.claude/settings.local.json
+
+# Local-only working notes and scratch files — never committed.
+.claude/local/
+
+# Internal planning docs — kept local, not committed to this repo. The
+# cast-build tooling under walkthrough/ stays tracked.
+/docs/strategy/
+/docs/internal/*
+!/docs/internal/walkthrough/
+/docs/internal/walkthrough/*
+!/docs/internal/walkthrough/build-poison-cast.ts
+
+# Python bytecode caches + build artifacts (runtimes/ — the LangGraph/CrewAI hooks)
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/

lodestar_langgraph-0.3.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: lodestar-langgraph
+Version: 0.3.0
+Summary: Govern a LangGraph agent's native tool calls with Lodestar — the thin native hook that remotes each tool call through the Lodestar Action Kernel over NDJSON-RPC (ADR-0024).
+Project-URL: Homepage, https://qmilab.com/lodestar
+Project-URL: Repository, https://github.com/qmilab/lodestar
+Project-URL: Issues, https://github.com/qmilab/lodestar/issues
+Author-email: QMI Lab <hello@qmilab.com>
+License: Apache-2.0
+Keywords: agents,ai-agents,governance,langgraph,lodestar,trust
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: lodestar-runtime-client==0.3.0
+Provides-Extra: dev
+Requires-Dist: langchain-core>=0.3.0; extra == 'dev'
+Requires-Dist: langgraph>=0.2.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: langgraph
+Requires-Dist: langchain-core>=0.3.0; extra == 'langgraph'
+Requires-Dist: langgraph>=0.2.0; extra == 'langgraph'
+Description-Content-Type: text/markdown
+
+# lodestar-langgraph
+
+Govern a **LangGraph** agent's native tool calls with
+[Lodestar](https://qmilab.com/lodestar) — the open epistemic-governance framework
+for AI agents.
+
+LangGraph runs tools natively in-process and does not speak MCP, so the MCP proxy
+cannot wrap it. This package is the **thin native hook** (ADR-0024): it spawns the
+TypeScript **governance-gate sidecar** (`lodestar runtime gate`) and remotes each
+native tool call through the Lodestar Action Kernel over newline-delimited
+JSON-RPC. The same machinery the MCP proxy runs — two-phase `propose → arbitrate →
+execute`, the signed policy gate, cognitive-core ingestion (external-document
+content can't auto-promote), sentinel arbitration, and the signed-approval L4 hold
+path — now applies to LangGraph, with no change to the engine.
+
+The tool body runs **only** inside the gate's execute phase, reached only after
+the gate (and any approval hold) clears: "tools that do work before approval are
+bugs" — across the Python↔TS boundary.
+
+## Install
+
+```bash
+pip install "lodestar-langgraph[langgraph]"
+# and the Lodestar CLI (Bun/npm), which provides `lodestar runtime gate`:
+npm install -g @qmilab/lodestar-cli   # or: bun add -g @qmilab/lodestar-cli
+```
+
+## Use
+
+```python
+from langgraph.prebuilt import ToolNode
+from lodestar_langgraph import GateClient, govern_tools, governed_call
+
+with GateClient("runtime-gate.config.json") as gate:
+    governed = govern_tools(gate, my_tools)      # register + wrap the toolset
+    llm = llm.bind_tools(governed)               # the model only sees governed tools
+    tool_node = ToolNode(governed)               # and so does the executor
+    # ... build and run your graph as usual; every tool call is now governed.
+
+    # A custom node invokes a governed tool through the helper, never raw:
+    result = governed_call(gate, "search_web", {"q": "lodestar"})
+```
+
+The gate's config (`runtime-gate.config.json`) is a `RuntimeGateConfig` — the
+signed policy document, approver keys, sentinel ids, persistence, and durable log
+root all live there. The hook never holds credentials or policy.
+
+## Scope (honest, ADR-0004 lineage)
+
+This is **governance over declared actions, not OS containment of the process.**
+Raw I/O performed *outside* the tool abstraction — a custom node that calls
+`requests.get()` directly instead of a registered tool — is outside the governed
+surface, exactly as `guard.wrap()` and the MCP proxy only govern the tools they
+are given. A call for an unregistered tool is **denied** (fail closed). Pair the
+adapter with network/filesystem controls for defense in depth.
+
+## Holds
+
+An L4 action the trust-ladder floor parks for approval is resolved by
+block-polling the gate up to the deadline for a *signed* approval (`hold_wait_ms`)
+— the headless default. For the idiomatic LangGraph `interrupt()` integration,
+call `gate.govern(...)` directly, raise `interrupt` with the returned `action_id`
+/ `request_id`, and call `gate.resume(...)` on `Command(resume=…)`.
+
+Apache-2.0. Part of the Lodestar monorepo (`runtimes/langgraph/`).

lodestar_langgraph-0.3.0/README.md

@@ -0,0 +1,65 @@
+# lodestar-langgraph
+
+Govern a **LangGraph** agent's native tool calls with
+[Lodestar](https://qmilab.com/lodestar) — the open epistemic-governance framework
+for AI agents.
+
+LangGraph runs tools natively in-process and does not speak MCP, so the MCP proxy
+cannot wrap it. This package is the **thin native hook** (ADR-0024): it spawns the
+TypeScript **governance-gate sidecar** (`lodestar runtime gate`) and remotes each
+native tool call through the Lodestar Action Kernel over newline-delimited
+JSON-RPC. The same machinery the MCP proxy runs — two-phase `propose → arbitrate →
+execute`, the signed policy gate, cognitive-core ingestion (external-document
+content can't auto-promote), sentinel arbitration, and the signed-approval L4 hold
+path — now applies to LangGraph, with no change to the engine.
+
+The tool body runs **only** inside the gate's execute phase, reached only after
+the gate (and any approval hold) clears: "tools that do work before approval are
+bugs" — across the Python↔TS boundary.
+
+## Install
+
+```bash
+pip install "lodestar-langgraph[langgraph]"
+# and the Lodestar CLI (Bun/npm), which provides `lodestar runtime gate`:
+npm install -g @qmilab/lodestar-cli   # or: bun add -g @qmilab/lodestar-cli
+```
+
+## Use
+
+```python
+from langgraph.prebuilt import ToolNode
+from lodestar_langgraph import GateClient, govern_tools, governed_call
+
+with GateClient("runtime-gate.config.json") as gate:
+    governed = govern_tools(gate, my_tools)      # register + wrap the toolset
+    llm = llm.bind_tools(governed)               # the model only sees governed tools
+    tool_node = ToolNode(governed)               # and so does the executor
+    # ... build and run your graph as usual; every tool call is now governed.
+
+    # A custom node invokes a governed tool through the helper, never raw:
+    result = governed_call(gate, "search_web", {"q": "lodestar"})
+```
+
+The gate's config (`runtime-gate.config.json`) is a `RuntimeGateConfig` — the
+signed policy document, approver keys, sentinel ids, persistence, and durable log
+root all live there. The hook never holds credentials or policy.
+
+## Scope (honest, ADR-0004 lineage)
+
+This is **governance over declared actions, not OS containment of the process.**
+Raw I/O performed *outside* the tool abstraction — a custom node that calls
+`requests.get()` directly instead of a registered tool — is outside the governed
+surface, exactly as `guard.wrap()` and the MCP proxy only govern the tools they
+are given. A call for an unregistered tool is **denied** (fail closed). Pair the
+adapter with network/filesystem controls for defense in depth.
+
+## Holds
+
+An L4 action the trust-ladder floor parks for approval is resolved by
+block-polling the gate up to the deadline for a *signed* approval (`hold_wait_ms`)
+— the headless default. For the idiomatic LangGraph `interrupt()` integration,
+call `gate.govern(...)` directly, raise `interrupt` with the returned `action_id`
+/ `request_id`, and call `gate.resume(...)` on `Command(resume=…)`.
+
+Apache-2.0. Part of the Lodestar monorepo (`runtimes/langgraph/`).

lodestar_langgraph-0.3.0/lodestar_langgraph/__init__.py

@@ -0,0 +1,38 @@
+"""lodestar-langgraph — govern a LangGraph agent's native tool calls with Lodestar.
+
+The thin native hook of the runtime-adapter epic (ADR-0024). It spawns the
+TypeScript governance-gate sidecar (``lodestar runtime gate``) and remotes each
+native LangGraph tool call through the Action Kernel over NDJSON-RPC — so the
+same two-phase execution, policy gate, cognitive-core ingestion, sentinel
+arbitration, and signed-approval hold path the MCP proxy runs now apply to a
+framework that does not speak MCP.
+
+Quick start::
+
+    from lodestar_langgraph import GateClient, govern_tools, governed_call
+
+    with GateClient("runtime-gate.config.json") as gate:
+        governed = govern_tools(gate, my_tools)
+        llm = llm.bind_tools(governed)
+        tool_node = ToolNode(governed)
+        # ... build and run your graph as usual ...
+"""
+
+from .adapter import (
+    DEFAULT_HOLD_WAIT_MS,
+    LodestarDenied,
+    govern_tools,
+    governed_call,
+)
+from lodestar_runtime_client import GateClient, GateError
+
+__all__ = [
+    "GateClient",
+    "GateError",
+    "govern_tools",
+    "governed_call",
+    "LodestarDenied",
+    "DEFAULT_HOLD_WAIT_MS",
+]
+
+__version__ = "0.3.0"

lodestar_langgraph-0.3.0/lodestar_langgraph/adapter.py

@@ -0,0 +1,169 @@
+"""LangGraph / LangChain integration for the Lodestar governance gate (ADR-0024).
+
+The adapter governs the framework's **tool-invocation surface** and nothing
+implicitly (ADR-0024 §3, one closed fail-closed surface):
+
+* :func:`govern_tools` registers every bound tool with the gate and returns
+  *wrapped* tools to hand to ``bind_tools`` AND the prebuilt ``ToolNode`` — a
+  governed wrapper is the only object the agent ever holds for a governed
+  capability. The wrapper routes each call through the gate (``propose →
+  arbitrate``); only on an ``allow`` does the gate remote the body back to run.
+* :func:`governed_call` is the helper a **custom node** uses to invoke a governed
+  tool — never a raw tool function.
+* A call for a tool that was never registered is **denied by the gate** (fail
+  closed). Raw I/O performed outside the tool abstraction is outside the governed
+  surface, exactly as ``guard.wrap()`` and the MCP proxy only govern the tools
+  they are given — pair with network/filesystem controls for defense in depth.
+
+Holds (an L4 action the trust-ladder floor parks for approval) are resolved by
+**block-polling** the gate up to the deadline for a *signed* approval
+(``hold_wait_ms``) — the headless default the ADR sanctions. For the idiomatic
+LangGraph ``interrupt()`` integration, call :func:`GateClient.govern` directly
+and raise ``interrupt`` with the returned ``action_id`` / ``request_id``, then
+:func:`GateClient.resume` on ``Command(resume=…)``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Callable, Iterable, Optional
+
+from lodestar_runtime_client import GateClient
+
+# Default block-poll budget for a held action, in ms. Keep comfortably under the
+# graph/client timeout; 0 means "don't wait" (surface the hold immediately).
+DEFAULT_HOLD_WAIT_MS = 60_000
+
+
+class LodestarDenied(Exception):
+    """A governed tool call was denied, held-then-timed-out, or failed.
+
+    ``kind`` is the machine tag from the gate (``policy_denied``,
+    ``approval_denied``, ``approval_timeout``, ``unregistered_tool``,
+    ``precondition_failed``, ``execution_failed``).
+    """
+
+    def __init__(self, reason: str, kind: str, action_id: Optional[str] = None) -> None:
+        super().__init__(reason)
+        self.reason = reason
+        self.kind = kind
+        self.action_id = action_id
+
+
+def governed_call(
+    client: GateClient,
+    tool: str,
+    args: dict,
+    *,
+    hold_wait_ms: int = DEFAULT_HOLD_WAIT_MS,
+) -> Any:
+    """Invoke a governed tool through the gate and return its output.
+
+    Drives the full two-phase flow: ``govern``; on a hold, block-poll ``resume``
+    up to ``hold_wait_ms`` for a signed approval; on completion, return the tool
+    output. Raises :class:`LodestarDenied` on any non-completion (including an
+    unregistered tool — fail closed). This is the helper a custom LangGraph node
+    calls; never invoke a raw tool function from a custom node.
+    """
+    result = client.govern(tool, args)
+    if result.get("phase") == "pending_approval":
+        result = client.resume(
+            str(result.get("action_id")),
+            str(result.get("request_id")),
+            wait_ms=hold_wait_ms,
+        )
+    phase = result.get("phase")
+    if phase == "completed":
+        return result.get("output")
+    raise LodestarDenied(
+        str(result.get("reason") or "governed tool call was not allowed"),
+        str(result.get("kind") or phase or "denied"),
+        result.get("action_id"),
+    )
+
+
+def govern_tools(
+    client: GateClient,
+    tools: Iterable[Any],
+    *,
+    hold_wait_ms: int = DEFAULT_HOLD_WAIT_MS,
+    on_denied: Optional[Callable[[LodestarDenied], Any]] = None,
+) -> list[Any]:
+    """Register and wrap a LangChain toolset for governance.
+
+    Returns governed ``StructuredTool``s to pass to BOTH ``llm.bind_tools(...)``
+    and the prebuilt ``ToolNode(...)``, so the agent never holds an ungoverned
+    handle. Each wrapper runs the call through the gate; the gate remotes the
+    *original* tool body back to run only inside its execute phase.
+
+    ``on_denied`` maps a :class:`LodestarDenied` to a tool return value (so a
+    ``ToolNode`` surfaces a re-plannable message rather than raising); the default
+    re-raises as a ``ToolException`` so the framework's own error handling
+    applies.
+    """
+    # Imported lazily so `from lodestar_langgraph import GateClient` works without
+    # langchain installed (the client is pure stdlib).
+    from langchain_core.tools import StructuredTool, ToolException
+
+    governed: list[Any] = []
+    for tool in tools:
+        name = tool.name
+        # Bind the ORIGINAL tool body for the gate's remoted execute. Using the
+        # original (not the wrapper) is what prevents recursion.
+        client.register_tool(name, _body_for(tool))
+        governed.append(_wrap_tool(client, tool, hold_wait_ms, on_denied, StructuredTool, ToolException))
+    return governed
+
+
+def _body_for(tool: Any) -> Callable[[dict], dict]:
+    """A run_tool body that executes the real LangChain tool and wraps its result
+    into the gate's tool-result shape.
+
+    The gate remotes the body on a worker thread with no running event loop, so we
+    use the synchronous ``tool.invoke`` for a tool with a sync implementation, and
+    fall back to running the coroutine for an **async-only** tool (one defined with
+    a ``coroutine`` and no sync ``func``): for such a tool ``invoke`` raises
+    ``NotImplementedError``, so it must go through ``ainvoke``. This serves both
+    sync and async tools regardless of whether the graph drove ``invoke`` or
+    ``ainvoke``.
+    """
+
+    def body(args: dict) -> dict:
+        try:
+            output = tool.invoke(args)
+        except NotImplementedError:
+            # Async-only tool: run its coroutine in this (loop-less) worker thread.
+            output = asyncio.run(tool.ainvoke(args))
+        documents: list[dict] = []
+        # A tool may surface untrusted document content for external_document
+        # evidence by returning {"output": ..., "_lodestar_documents": [...]}.
+        if isinstance(output, dict) and "_lodestar_documents" in output:
+            documents = list(output.get("_lodestar_documents") or [])
+            output = output.get("output")
+        return {"output": output, "documents": documents}
+
+    return body
+
+
+def _wrap_tool(
+    client: GateClient,
+    tool: Any,
+    hold_wait_ms: int,
+    on_denied: Optional[Callable[[LodestarDenied], Any]],
+    structured_tool_cls: Any,
+    tool_exception_cls: Any,
+) -> Any:
+    def governed_func(**kwargs: Any) -> Any:
+        try:
+            return governed_call(client, tool.name, kwargs, hold_wait_ms=hold_wait_ms)
+        except LodestarDenied as denied:
+            if on_denied is not None:
+                return on_denied(denied)
+            raise tool_exception_cls(f"[lodestar:{denied.kind}] {denied.reason}") from denied
+
+    return structured_tool_cls.from_function(
+        func=governed_func,
+        name=tool.name,
+        description=getattr(tool, "description", "") or tool.name,
+        args_schema=getattr(tool, "args_schema", None),
+    )

lodestar_langgraph-0.3.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lodestar-langgraph"
+version = "0.3.0"
+description = "Govern a LangGraph agent's native tool calls with Lodestar — the thin native hook that remotes each tool call through the Lodestar Action Kernel over NDJSON-RPC (ADR-0024)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "QMI Lab", email = "hello@qmilab.com" }]
+keywords = ["ai-agents", "langgraph", "governance", "lodestar", "trust", "agents"]
+classifiers = [
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Intended Audience :: Developers",
+]
+# The Lodestar RPC client (spawns the TS gate, speaks NDJSON over stdio) is the
+# pure-stdlib `lodestar-runtime-client`, shared across the runtime hooks (#128,
+# ADR-0028) and pinned in lockstep with this package. The LangGraph/LangChain
+# integration in `adapter` imports langchain lazily; install the `langgraph` extra.
+dependencies = ["lodestar-runtime-client==0.3.0"]
+
+[project.optional-dependencies]
+langgraph = ["langgraph>=0.2.0", "langchain-core>=0.3.0"]
+dev = ["langgraph>=0.2.0", "langchain-core>=0.3.0", "pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://qmilab.com/lodestar"
+Repository = "https://github.com/qmilab/lodestar"
+Issues = "https://github.com/qmilab/lodestar/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["lodestar_langgraph"]

lodestar_langgraph-0.3.0/tests/e2e_langgraph.py

@@ -0,0 +1,281 @@
+#!/usr/bin/env python3
+"""End-to-end driver for the LangGraph runtime adapter (ADR-0024 §8).
+
+Drives a REAL Python LangGraph loop through the `lodestar-langgraph` hook and the
+TypeScript governance-gate sidecar, exercising the real-runtime cases the in-TS
+`runtime-gate-enforces-two-phase` probe cannot:
+
+  1. the prebuilt ``ToolNode`` runs only governed wrappers (a governed L1 call
+     executes; the body runs exactly once, remoted back from the gate);
+  2. a custom node invokes a governed tool via ``governed_call``;
+  3. async invocation (``ToolNode.ainvoke``);
+  4. batch / parallel invocation (``ToolNode.batch``) — correlated correctly;
+  5. an L4 tool is HELD (two-phase across the boundary): with no approver it
+     times out and the body NEVER runs;
+  6. a tool that was never registered is DENIED — fail closed.
+
+Spawns the gate via ``bun run <repo>/packages/cli/src/index.ts runtime gate``.
+Invoked by the runtime-gated ``langgraph-tool-calls-are-governed`` probe, which
+skips loudly when Python / LangGraph is absent. Exit 0 = pass, 1 = fail.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import math
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+CLI_INDEX = REPO_ROOT / "packages" / "cli" / "src" / "index.ts"
+
+# Prefer the INSTALLED hook so CI (which pip-installs runtimes/langgraph) actually
+# exercises the packaged artifact and its pyproject exports. Only fall back to the
+# source tree for a local run where the hook isn't installed.
+try:
+    from lodestar_langgraph import (  # noqa: E402
+        GateClient,
+        GateError,
+        LodestarDenied,
+        govern_tools,
+        governed_call,
+    )
+except ImportError:
+    # The hook's source __init__ imports lodestar_runtime_client (#128); put the
+    # shared client's source on the path too so the no-install fallback resolves it.
+    sys.path.insert(0, str(REPO_ROOT / "runtimes" / "runtime-client"))
+    sys.path.insert(0, str(REPO_ROOT / "runtimes" / "langgraph"))
+    from lodestar_langgraph import (  # noqa: E402
+        GateClient,
+        GateError,
+        LodestarDenied,
+        govern_tools,
+        governed_call,
+    )
+
+try:
+    from langchain_core.messages import AIMessage
+    from langchain_core.tools import StructuredTool
+    from langgraph.graph import END, START, MessagesState, StateGraph
+    from langgraph.prebuilt import ToolNode
+except Exception as exc:  # pragma: no cover - the probe gates on import availability
+    print(f"SKIP: LangGraph/LangChain not importable: {exc}")
+    sys.exit(0)
+
+# ── tool bodies (the REAL functions the gate remotes back to run) ─────────────
+runs: dict[str, int] = {"echo": 0, "read_doc": 0, "deploy": 0, "fetch": 0}
+
+
+def echo(msg: str) -> dict:
+    runs["echo"] += 1
+    return {"echo": msg}
+
+
+def read_doc(path: str) -> dict:
+    runs["read_doc"] += 1
+    # Surface untrusted document content for external_document evidence.
+    return {"output": {"read": path}, "_lodestar_documents": [{"text": "untrusted file body", "source": path}]}
+
+
+def deploy(target: str) -> dict:
+    runs["deploy"] += 1  # must stay 0 for a held L4 with no approver
+    return {"deployed": target}
+
+
+async def fetch(url: str) -> dict:
+    # An ASYNC-ONLY tool body (coroutine, no sync impl): the gate remotes it on a
+    # loop-less worker thread, so the hook must run it via ainvoke, not sync invoke.
+    runs["fetch"] += 1
+    return {"fetched": url}
+
+
+def nan_out(x: int) -> dict:
+    # A tool whose result carries a non-finite float — invalid JSON for the gate.
+    # The hook must reject it (→ tool_error → failed action), never emit `NaN`.
+    return {"output": {"value": float("nan")}}
+
+
+def make_tool(fn) -> StructuredTool:
+    return StructuredTool.from_function(func=fn, name=fn.__name__, description=fn.__name__)
+
+
+def make_async_tool(coro) -> StructuredTool:
+    return StructuredTool.from_function(coroutine=coro, name=coro.__name__, description=coro.__name__)
+
+
+def tool_call(name: str, args: dict, call_id: str) -> AIMessage:
+    return AIMessage(content="", tool_calls=[{"name": name, "args": args, "id": call_id, "type": "tool_call"}])
+
+
+failures: list[str] = []
+
+
+def check(label: str, cond: bool, extra: str = "") -> None:
+    status = "PASS" if cond else "FAIL"
+    print(f"  [{status}] {label}" + (f" — {extra}" if extra else ""))
+    if not cond:
+        failures.append(label)
+
+
+def main() -> int:
+    with tempfile.TemporaryDirectory() as tmp:
+        log_root = str(Path(tmp) / "events")
+        config = {
+            "project_id": "langgraph-e2e",
+            "actor_id": "langgraph-agent",
+            "session_id": "auto",
+            "log_root": log_root,
+            "default_scope": {"level": "session", "identifier": "langgraph-e2e"},
+            "default_sensitivity": "internal",
+            "auto_approve_ceiling": 3,
+            # An L4 hold parks; with no approver it must time out fast here.
+            "approval_timeout_ms": 300,
+            "approvals": {"allow_unsigned": True},
+            "tool_defaults": {
+                "echo": {"required_trust_level": 1, "reversibility": "reversible", "sandbox": "read", "permissions": [], "blast_radius": "session"},
+                "read_doc": {"required_trust_level": 1, "reversibility": "reversible", "sandbox": "read", "permissions": [], "blast_radius": "session"},
+                "deploy": {"required_trust_level": 4, "reversibility": "irreversible", "sandbox": "controlled-shell", "permissions": [], "blast_radius": "external"},
+                "fetch": {"required_trust_level": 1, "reversibility": "reversible", "sandbox": "read", "permissions": [], "blast_radius": "session"},
+                "nan_out": {"required_trust_level": 1, "reversibility": "reversible", "sandbox": "read", "permissions": [], "blast_radius": "session"},
+            },
+        }
+        config_path = Path(tmp) / "runtime-gate.config.json"
+        config_path.write_text(json.dumps(config))
+
+        # P3: a sidecar that exits before `ready` (here: an invalid config the CLI
+        # rejects) must fail construction FAST with a useful message, not block the
+        # full ready timeout.
+        bad_config = Path(tmp) / "bad.config.json"
+        bad_config.write_text("{}")  # missing required fields → the CLI exits 1
+        t0 = time.monotonic()
+        startup_err = None
+        try:
+            GateClient(str(bad_config), launcher=["bun", "run", str(CLI_INDEX)], ready_timeout_s=20)
+        except GateError as exc:
+            startup_err = str(exc)
+        elapsed = time.monotonic() - t0
+        check("P3: bad-config startup fails fast (not after the ready timeout)", startup_err is not None and elapsed < 10, f"{elapsed:.1f}s")
+        check("P3: the failure reports the gate exited before ready", startup_err is not None and "before signalling ready" in startup_err, str(startup_err))
+
+        with GateClient(str(config_path), launcher=["bun", "run", str(CLI_INDEX)]) as gate:
+            print("─" * 72)
+            print("langgraph-tool-calls-are-governed (real LangGraph ToolNode + hook + gate)")
+            print("─" * 72)
+
+            tools = [
+                make_tool(echo),
+                make_tool(read_doc),
+                make_tool(deploy),
+                make_async_tool(fetch),
+                make_tool(nan_out),
+            ]
+            governed = govern_tools(gate, tools, hold_wait_ms=2_000)
+            governed_by_name = {t.name: t for t in governed}
+            check("0: only governed wrappers are exposed", set(governed_by_name) == {"echo", "read_doc", "deploy", "fetch", "nan_out"}, str(set(governed_by_name)))
+
+            # Build a real compiled LangGraph with the prebuilt ToolNode. Driving
+            # the node through a compiled graph (rather than a bare ToolNode.invoke)
+            # is the faithful "LangGraph loop" — it provides the runtime config the
+            # node needs and is how an agent actually runs it.
+            tool_node = ToolNode(governed)
+            graph = StateGraph(MessagesState)
+            graph.add_node("tools", tool_node)
+            graph.add_edge(START, "tools")
+            graph.add_edge("tools", END)
+            app = graph.compile()
+
+            def last_content(out: dict) -> str:
+                return str(out["messages"][-1].content)
+
+            # 1. the compiled graph's ToolNode runs a governed L1 tool; body once.
+            out = app.invoke({"messages": [tool_call("echo", {"msg": "hi"}, "c1")]})
+            check("1: ToolNode (compiled graph) ran the governed echo", "hi" in last_content(out), last_content(out))
+            check("1: echo body ran exactly once", runs["echo"] == 1, str(runs["echo"]))
+
+            # 2. custom node via governed_call.
+            res = governed_call(gate, "echo", {"msg": "from-node"})
+            check("2: governed_call returned the tool output", res == {"echo": "from-node"}, str(res))
+            check("2: echo body ran again exactly once", runs["echo"] == 2, str(runs["echo"]))
+
+            # 3. async invocation through the compiled graph (ainvoke).
+            aout = asyncio.run(app.ainvoke({"messages": [tool_call("read_doc", {"path": "/x"}, "c2")]}))
+            check("3: ainvoke ran the governed read_doc", "read" in last_content(aout), last_content(aout))
+            check("3: read_doc body ran once (async)", runs["read_doc"] == 1, str(runs["read_doc"]))
+
+            # 4. batch / parallel invocation — each correlated to its own result.
+            before = runs["echo"]
+            batch_out = app.batch(
+                [
+                    {"messages": [tool_call("echo", {"msg": "B1"}, "b1")]},
+                    {"messages": [tool_call("echo", {"msg": "B2"}, "b2")]},
+                ]
+            )
+            contents = [last_content(o) for o in batch_out]
+            check("4: batch call B1 correlated", any("B1" in c for c in contents), str(contents))
+            check("4: batch call B2 correlated", any("B2" in c for c in contents), str(contents))
+            check("4: both batch bodies ran", runs["echo"] - before == 2, str(runs["echo"] - before))
+
+            # 5. L4 tool is HELD (two-phase across the boundary): with no approver
+            #    it times out and the body NEVER runs.
+            deploy_before = runs["deploy"]
+            denied_kind = None
+            try:
+                governed_call(gate, "deploy", {"target": "prod"}, hold_wait_ms=2_000)
+            except LodestarDenied as denied:
+                denied_kind = denied.kind
+            check("5: L4 deploy was held then denied", denied_kind == "approval_timeout", str(denied_kind))
+            check("5: deploy body NEVER ran (no work before approval)", runs["deploy"] - deploy_before == 0, str(runs["deploy"] - deploy_before))
+
+            # 6. a tool that was never registered is denied — fail closed.
+            ghost_kind = None
+            try:
+                governed_call(gate, "never_registered", {})
+            except LodestarDenied as denied:
+                ghost_kind = denied.kind
+            check("6: unregistered tool denied (fail closed)", ghost_kind == "unregistered_tool", str(ghost_kind))
+
+            # 7. an ASYNC-ONLY tool body runs through the gate's remoted execute
+            #    (the hook must ainvoke it on the loop-less worker thread, not the
+            #    failing sync invoke path). Exercised via the compiled graph's
+            #    ainvoke AND a direct governed_call.
+            afetch = asyncio.run(app.ainvoke({"messages": [tool_call("fetch", {"url": "https://x"}, "c3")]}))
+            check("7: async-only tool ran via ToolNode ainvoke", "fetched" in last_content(afetch), last_content(afetch))
+            res_async = governed_call(gate, "fetch", {"url": "https://y"})
+            check("7: async-only tool ran via governed_call", res_async == {"fetched": "https://y"}, str(res_async))
+            check("7: async tool body ran exactly twice", runs["fetch"] == 2, str(runs["fetch"]))
+
+            # 8. Non-finite floats are rejected before they corrupt the JSON wire,
+            #    so a NaN in args or a tool result fails the call rather than hanging
+            #    it (Python's json.dumps would otherwise emit invalid `NaN`).
+            arg_nan_err = None
+            try:
+                governed_call(gate, "echo", {"msg": math.nan})
+            except GateError:
+                arg_nan_err = "gate_error"
+            except LodestarDenied as denied:
+                arg_nan_err = denied.kind
+            check("8: a NaN argument is rejected, not silently hung", arg_nan_err is not None, str(arg_nan_err))
+
+            out_nan_err = None
+            try:
+                governed_call(gate, "nan_out", {"x": 1})
+            except LodestarDenied as denied:
+                out_nan_err = denied.kind
+            except GateError:
+                out_nan_err = "gate_error"
+            check("8: a NaN tool result fails the action, not silently hung", out_nan_err is not None, str(out_nan_err))
+
+            print("─" * 72)
+            if failures:
+                print(f"RESULT: FAIL ({len(failures)} check(s) failed)")
+            else:
+                print("RESULT: PASS — LangGraph native tool calls are governed end-to-end")
+            print("─" * 72)
+            return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())