lodestar-autogen 0.3.0__tar.gz

lodestar_autogen-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_autogen-0.3.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: lodestar-autogen
+Version: 0.3.0
+Summary: Govern an AutoGen 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-0027).
+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,autogen,governance,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: autogen
+Requires-Dist: autogen-agentchat>=0.4; extra == 'autogen'
+Requires-Dist: autogen-core>=0.4; extra == 'autogen'
+Provides-Extra: dev
+Requires-Dist: autogen-agentchat>=0.4; extra == 'dev'
+Requires-Dist: autogen-core>=0.4; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lodestar-autogen
+
+Govern an **AutoGen** agent's native tool calls with
+[Lodestar](https://qmilab.com/lodestar) — the open epistemic-governance framework
+for AI agents.
+
+AutoGen (the `autogen-agentchat` / `autogen-core` actor framework) runs
+multi-agent conversations whose tools are native in-process Python objects and
+does not speak MCP, so the MCP proxy cannot wrap it. This package is the **thin
+native hook** (ADR-0027) — the third framework on the same shared gate, after
+LangGraph and CrewAI: 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
+and the LangGraph / CrewAI adapters run — 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 AutoGen, with no change to the engine. The gate sidecar is
+shared, unchanged; only this hook is new.
+
+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-autogen[autogen]"
+# 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 autogen_agentchat.agents import AssistantAgent
+from lodestar_autogen import GateClient, govern_tools, governed_call
+
+with GateClient("runtime-gate.config.json") as gate:
+    governed = govern_tools(gate, my_tools)        # register + wrap the toolset
+    agent = AssistantAgent("assistant", model_client=model_client, tools=governed)
+    # ... run your agent / team as usual; every tool call is governed.
+
+    # A custom step invokes a governed tool through the helper, never raw.
+    # It blocks, so off the event loop call it via a worker thread:
+    import asyncio
+    result = await asyncio.to_thread(governed_call, gate, "search_web", {"q": "lodestar"})
+```
+
+`govern_tools` accepts the same toolset shapes `AssistantAgent` does — a
+`BaseTool` as-is, or a **bare callable** (normalised to a `FunctionTool` using its
+docstring), so you can pass the literal `tools=[my_func, ...]` list you'd otherwise
+hand the agent.
+
+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 step 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 & denials
+
+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. A denied / held-then-timed-out call raises
+`LodestarDenied` by default; AutoGen's `StaticWorkbench.call_tool` catches it and
+surfaces the reason to the agent as a re-plannable error `ToolResult`. Pass
+`on_denied` to `govern_tools` to map a denial to a return value instead.
+
+## Async, loops & cancellation
+
+AutoGen's tool surface is fully async (`BaseTool.run_json` is a coroutine). The
+governed wrapper offloads the blocking gate RPC onto a worker thread so it never
+stalls the agent's event loop, and the gate's remoted body runs the original
+tool's coroutine on a single **persistent** event loop — so loop-scoped state a
+tool caches (an `aiohttp.ClientSession`, an `asyncio.Event`) stays valid across
+calls rather than being bound to a loop that is torn down after each call.
+
+The wrapper honours AutoGen's `CancellationToken`: an already-cancelled token
+short-circuits (no governed work starts), and an in-flight call is unblocked when
+the run is cancelled. Note that once the gate is executing the tool body it runs
+server-side and can't be force-cancelled mid-flight — a property of the
+remoted-execute model it shares with the LangGraph / CrewAI hooks.
+
+Apache-2.0. Part of the Lodestar monorepo (`runtimes/autogen/`). The pure-stdlib
+`client.py` is duplicated verbatim from `lodestar-langgraph` / `lodestar-crewai`;
+it graduates to a shared `lodestar-runtime-client` package alongside PyPI
+publishing (issue #128).

lodestar_autogen-0.3.0/README.md

@@ -0,0 +1,94 @@
+# lodestar-autogen
+
+Govern an **AutoGen** agent's native tool calls with
+[Lodestar](https://qmilab.com/lodestar) — the open epistemic-governance framework
+for AI agents.
+
+AutoGen (the `autogen-agentchat` / `autogen-core` actor framework) runs
+multi-agent conversations whose tools are native in-process Python objects and
+does not speak MCP, so the MCP proxy cannot wrap it. This package is the **thin
+native hook** (ADR-0027) — the third framework on the same shared gate, after
+LangGraph and CrewAI: 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
+and the LangGraph / CrewAI adapters run — 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 AutoGen, with no change to the engine. The gate sidecar is
+shared, unchanged; only this hook is new.
+
+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-autogen[autogen]"
+# 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 autogen_agentchat.agents import AssistantAgent
+from lodestar_autogen import GateClient, govern_tools, governed_call
+
+with GateClient("runtime-gate.config.json") as gate:
+    governed = govern_tools(gate, my_tools)        # register + wrap the toolset
+    agent = AssistantAgent("assistant", model_client=model_client, tools=governed)
+    # ... run your agent / team as usual; every tool call is governed.
+
+    # A custom step invokes a governed tool through the helper, never raw.
+    # It blocks, so off the event loop call it via a worker thread:
+    import asyncio
+    result = await asyncio.to_thread(governed_call, gate, "search_web", {"q": "lodestar"})
+```
+
+`govern_tools` accepts the same toolset shapes `AssistantAgent` does — a
+`BaseTool` as-is, or a **bare callable** (normalised to a `FunctionTool` using its
+docstring), so you can pass the literal `tools=[my_func, ...]` list you'd otherwise
+hand the agent.
+
+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 step 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 & denials
+
+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. A denied / held-then-timed-out call raises
+`LodestarDenied` by default; AutoGen's `StaticWorkbench.call_tool` catches it and
+surfaces the reason to the agent as a re-plannable error `ToolResult`. Pass
+`on_denied` to `govern_tools` to map a denial to a return value instead.
+
+## Async, loops & cancellation
+
+AutoGen's tool surface is fully async (`BaseTool.run_json` is a coroutine). The
+governed wrapper offloads the blocking gate RPC onto a worker thread so it never
+stalls the agent's event loop, and the gate's remoted body runs the original
+tool's coroutine on a single **persistent** event loop — so loop-scoped state a
+tool caches (an `aiohttp.ClientSession`, an `asyncio.Event`) stays valid across
+calls rather than being bound to a loop that is torn down after each call.
+
+The wrapper honours AutoGen's `CancellationToken`: an already-cancelled token
+short-circuits (no governed work starts), and an in-flight call is unblocked when
+the run is cancelled. Note that once the gate is executing the tool body it runs
+server-side and can't be force-cancelled mid-flight — a property of the
+remoted-execute model it shares with the LangGraph / CrewAI hooks.
+
+Apache-2.0. Part of the Lodestar monorepo (`runtimes/autogen/`). The pure-stdlib
+`client.py` is duplicated verbatim from `lodestar-langgraph` / `lodestar-crewai`;
+it graduates to a shared `lodestar-runtime-client` package alongside PyPI
+publishing (issue #128).

lodestar_autogen-0.3.0/lodestar_autogen/__init__.py

@@ -0,0 +1,40 @@
+"""lodestar-autogen — govern an AutoGen agent's native tool calls with Lodestar.
+
+The thin native hook of the runtime-adapter epic (ADR-0024 / ADR-0027), and the
+third framework on the same shared gate (after LangGraph and CrewAI). It spawns
+the TypeScript governance-gate sidecar (``lodestar runtime gate``) and remotes
+each native AutoGen 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 and the LangGraph /
+CrewAI adapters run now apply to AutoGen, a framework that does not speak MCP. The
+gate sidecar is shared, unchanged; only this hook is new.
+
+Quick start::
+
+    from autogen_agentchat.agents import AssistantAgent
+    from lodestar_autogen import GateClient, govern_tools, governed_call
+
+    with GateClient("runtime-gate.config.json") as gate:
+        governed = govern_tools(gate, my_tools)   # register + wrap the toolset
+        agent = AssistantAgent("assistant", model_client=..., tools=governed)
+        # ... run your agent/team as usual; every tool call is now governed.
+"""
+
+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_autogen-0.3.0/lodestar_autogen/adapter.py

@@ -0,0 +1,332 @@
+"""AutoGen integration for the Lodestar governance gate (ADR-0024 / ADR-0027).
+
+AutoGen (the ``autogen-agentchat`` / ``autogen-core`` actor framework) runs
+multi-agent conversations whose tools are native in-process
+``autogen_core.tools.BaseTool`` objects; it does not speak MCP, so the MCP proxy
+cannot wrap it. This adapter is the thin native hook (ADR-0027): it reuses the
+**same** language-agnostic governance-gate sidecar the LangGraph and CrewAI
+adapters do and governs AutoGen's **tool-invocation surface** and nothing
+implicitly (ADR-0024 §3, one closed fail-closed surface):
+
+* :func:`govern_tools` registers every tool with the gate and returns *wrapped*
+  ``BaseTool``s to hand to the ``AssistantAgent`` (and any ``Workbench``) — a
+  governed wrapper is the only object an 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.
+  The wrapper overrides ``run_json`` — the exact point AutoGen executes a tool
+  through (``AssistantAgent`` dispatches via ``StaticWorkbench.call_tool``, which
+  calls ``tool.run_json``; a direct caller hits the same method).
+* :func:`governed_call` is the helper a **custom step** (a callback / handler that
+  invokes a tool directly) uses to call a governed tool — never a raw tool body.
+* 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.
+
+When a governed call is denied/held-then-timed-out, the default re-raises
+:class:`LodestarDenied`; AutoGen's ``StaticWorkbench.call_tool`` catches it and
+surfaces the reason to the agent as a re-plannable error ``ToolResult``. Pass
+``on_denied`` to map a denial to a return value instead.
+
+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.
+
+AutoGen's tool surface is **fully async** (``run`` / ``run_json`` are coroutines).
+The governed wrapper therefore offloads the blocking gate RPC onto a worker thread
+(:func:`asyncio.to_thread`) so it never stalls the agent's event loop, and the
+gate's remoted body runs the original tool's coroutine via ``asyncio.run`` on the
+client's (loop-less) worker thread.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+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
+# gate/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 AutoGen step
+    calls; never invoke a raw tool body from a custom step.
+
+    This call **blocks**; from inside an AutoGen coroutine, call it via
+    ``await asyncio.to_thread(governed_call, ...)`` so it does not stall the loop
+    (the governed-tool wrapper already does this for the agent's own tool calls).
+    """
+    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 an AutoGen toolset for governance.
+
+    Returns governed ``BaseTool``s to assign to your ``AssistantAgent`` (and any
+    ``Workbench``), so an 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; the
+    default re-raises, which AutoGen's ``StaticWorkbench.call_tool`` turns into a
+    re-plannable error ``ToolResult`` for the agent.
+    """
+    # Imported lazily so `from lodestar_autogen import GateClient` works without
+    # autogen installed (the client is pure stdlib). pydantic + CancellationToken
+    # come in with autogen-core.
+    from autogen_core import CancellationToken
+    from autogen_core.tools import BaseTool, FunctionTool
+    from pydantic import BaseModel
+
+    cls = _governed_tool_cls()
+    governed: list[Any] = []
+    for tool in tools:
+        # Accept the same toolset shapes AssistantAgent does — a BaseTool as-is, a
+        # bare callable normalised to a FunctionTool — so `govern_tools(gate, tools)`
+        # works on the exact `tools=[...]` list the agent would take, not only
+        # pre-wrapped BaseTools.
+        tool = _normalize_tool(tool, BaseTool, FunctionTool)
+        # Bind the ORIGINAL tool body for the gate's remoted execute. Using the
+        # original (not the wrapper) is what prevents recursion.
+        client.register_tool(tool.name, _body_for(tool, CancellationToken, BaseModel))
+        governed.append(_wrap_tool(cls, client, tool, hold_wait_ms, on_denied))
+    return governed
+
+
+def _normalize_tool(tool: Any, base_tool_cls: Any, function_tool_cls: Any) -> Any:
+    """Mirror ``AssistantAgent``'s tool ingestion: a ``BaseTool`` is used as-is; a
+    bare callable is wrapped in a ``FunctionTool`` (its ``__doc__`` as the
+    description, exactly as the agent does). So ``govern_tools`` accepts the same
+    ``tools=[...]`` shapes the framework does — passing a plain function no longer
+    fails on a missing ``.name``."""
+    if isinstance(tool, base_tool_cls):
+        return tool
+    if callable(tool):
+        description = tool.__doc__ if getattr(tool, "__doc__", None) else ""
+        return function_tool_cls(tool, description=description)
+    raise TypeError(f"govern_tools: unsupported tool type {type(tool)!r}")
+
+
+# A single persistent event loop on a dedicated daemon thread runs every remoted
+# tool coroutine. AutoGen's tool surface is *fully* async, so a fresh `asyncio.run`
+# per call would bind any loop-scoped state a tool caches (an `aiohttp.ClientSession`,
+# an `asyncio.Event`/`Queue`, a pooled DB connection) to a loop that is then torn
+# down — the next call on a new loop would fail cross-loop. One stable loop keeps
+# that state valid across calls. Lazily created; never touched on the import path.
+_tool_loop_lock = threading.Lock()
+_tool_loop_holder: dict[str, Any] = {"loop": None}
+
+
+def _tool_loop() -> Any:
+    with _tool_loop_lock:
+        loop = _tool_loop_holder["loop"]
+        if loop is None:
+            loop = asyncio.new_event_loop()
+            threading.Thread(
+                target=loop.run_forever, name="lodestar-autogen-tool-loop", daemon=True
+            ).start()
+            _tool_loop_holder["loop"] = loop
+    return loop
+
+
+def _body_for(tool: Any, cancellation_token_cls: Any, base_model_cls: Any) -> Callable[[dict], dict]:
+    """A run_tool body that executes the real AutoGen tool and wraps its result
+    into the gate's tool-result shape.
+
+    AutoGen's tool surface is fully async — ``run_json`` validates the args against
+    the tool's ``args_type`` and awaits ``run``. The gate remotes this body on a
+    worker thread with no running event loop; we drive the coroutine on the shared
+    persistent tool loop (so loop-scoped state a tool caches survives across calls,
+    unlike a fresh ``asyncio.run`` per call) and block this worker thread on the
+    result. A Pydantic-model result is dumped to a JSON-safe value for the wire; a
+    non-finite float is rejected by the client before it can corrupt the JSON (→
+    ``tool_error`` → failed action), never silently emitted as ``NaN``.
+    """
+
+    def body(args: dict) -> dict:
+        loop = _tool_loop()
+        future = asyncio.run_coroutine_threadsafe(tool.run_json(args, cancellation_token_cls()), loop)
+        output = future.result()
+        # Normalise a Pydantic-model return to a JSON-safe value for the wire.
+        if isinstance(output, base_model_cls):
+            output = output.model_dump(mode="json")
+        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
+
+
+# The governed BaseTool subclass is built once, lazily — so importing
+# `lodestar_autogen` (e.g. `from lodestar_autogen import GateClient`) does not require
+# autogen installed (the client is pure stdlib). Cached module-wide.
+_GOVERNED_TOOL_CLS: Optional[type] = None
+
+
+def _governed_tool_cls() -> type:
+    global _GOVERNED_TOOL_CLS
+    if _GOVERNED_TOOL_CLS is not None:
+        return _GOVERNED_TOOL_CLS
+    # Imported lazily; see above.
+    from autogen_core import CancellationToken
+    from autogen_core.tools import BaseTool
+
+    class _GovernedAutoGenTool(BaseTool):  # type: ignore[type-arg]
+        """A governed ``BaseTool`` that presents the original's schema but routes
+        every call through the gate. Not a Pydantic model (AutoGen's ``BaseTool``
+        is a plain class), so the gate reference + per-tool config live in plain
+        instance attributes — they are never part of the tool's serialised schema
+        (the description the LLM sees) and are not validated as tool inputs.
+        """
+
+        def __init__(self, original: Any, gov: dict) -> None:
+            super().__init__(
+                args_type=original.args_type(),
+                return_type=original.return_type(),
+                name=original.name,
+                description=original.description,
+                strict=bool(getattr(original, "_strict", False)),
+            )
+            self._original = original
+            self._gov = gov
+
+        # Delegate the schema surface to the original so a custom override (or a
+        # FunctionTool's generated schema) is preserved verbatim — the model sees
+        # exactly the original's parameters, not one regenerated from the wrapper.
+        @property
+        def schema(self) -> Any:
+            return self._original.schema
+
+        def args_type(self) -> Any:
+            return self._original.args_type()
+
+        def return_type(self) -> Any:
+            return self._original.return_type()
+
+        def state_type(self) -> Any:
+            return self._original.state_type()
+
+        def return_value_as_string(self, value: Any) -> str:
+            # The value has crossed the JSON wire, so it is a str / dict / list /
+            # primitive (not the original Pydantic model). Stringify deterministically.
+            if isinstance(value, str):
+                return value
+            try:
+                return json.dumps(value)
+            except (TypeError, ValueError):
+                return str(value)
+
+        async def run_json(self, args: Any, cancellation_token: Any = None, call_id: Optional[str] = None) -> Any:
+            # The choke point the workbench / agent dispatches through.
+            return await self._governed(dict(args or {}), cancellation_token)
+
+        async def run(self, args: Any, cancellation_token: Any = None) -> Any:
+            # The abstract method; also governs a direct programmatic caller that
+            # already validated its args into the model. run_json does NOT delegate
+            # here, so there is no double-governing.
+            payload = args.model_dump() if hasattr(args, "model_dump") else dict(args or {})
+            return await self._governed(payload, cancellation_token)
+
+        async def _governed(self, payload: dict, cancellation_token: Any = None) -> Any:
+            gov = self._gov
+            # Honour an already-cancelled run: don't even propose the action, so a
+            # cancelled agent run starts no new governed work (no body, no event).
+            if cancellation_token is not None and cancellation_token.is_cancelled():
+                raise asyncio.CancelledError()
+            # Offload the blocking gate RPC onto a worker thread so the agent's event
+            # loop is never stalled by govern/resume; link the agent's cancellation
+            # token so cancelling the run promptly unblocks this await. NOTE: once the
+            # gate reaches its execute phase the remoted body runs server-side and
+            # cannot be force-cancelled across the RPC boundary — a documented boundary
+            # of the remoted-execute model (ADR-0027 §2). The early-cancel check above
+            # is what prevents a *new* call from starting on an already-cancelled run.
+            task = asyncio.ensure_future(
+                asyncio.to_thread(governed_call, gov["client"], gov["name"], payload, hold_wait_ms=gov["hold_wait_ms"])
+            )
+            if cancellation_token is not None:
+                cancellation_token.link_future(task)
+            try:
+                return await task
+            except LodestarDenied as denied:
+                on_denied = gov["on_denied"]
+                if on_denied is not None:
+                    return on_denied(denied)
+                # Re-raise: AutoGen's StaticWorkbench.call_tool catches it and
+                # surfaces the reason as a re-plannable error ToolResult.
+                raise
+
+    _GOVERNED_TOOL_CLS = _GovernedAutoGenTool
+    return _GOVERNED_TOOL_CLS
+
+
+def _wrap_tool(
+    cls: type,
+    client: GateClient,
+    tool: Any,
+    hold_wait_ms: int,
+    on_denied: Optional[Callable[[LodestarDenied], Any]],
+) -> Any:
+    return cls(
+        tool,
+        {
+            "client": client,
+            "name": tool.name,
+            "hold_wait_ms": hold_wait_ms,
+            "on_denied": on_denied,
+        },
+    )

lodestar_autogen-0.3.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lodestar-autogen"
+version = "0.3.0"
+description = "Govern an AutoGen 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-0027)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "QMI Lab", email = "hello@qmilab.com" }]
+keywords = ["ai-agents", "autogen", "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 AutoGen integration in
+# `adapter` imports autogen lazily; install the `autogen` extra.
+dependencies = ["lodestar-runtime-client==0.3.0"]
+
+[project.optional-dependencies]
+# autogen-agentchat pulls autogen-core (where BaseTool / CancellationToken live).
+# Verified against autogen-core / autogen-agentchat 0.7.5; the seam (BaseTool.run_json
+# via StaticWorkbench.call_tool) has been stable across the 0.4+ actor line.
+autogen = ["autogen-agentchat>=0.4", "autogen-core>=0.4"]
+dev = ["autogen-agentchat>=0.4", "autogen-core>=0.4", "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_autogen"]

lodestar_autogen-0.3.0/tests/e2e_autogen.py

@@ -0,0 +1,420 @@
+#!/usr/bin/env python3
+"""End-to-end driver for the AutoGen runtime adapter (ADR-0027 / ADR-0024 §8).
+
+Drives REAL AutoGen tools through the `lodestar-autogen` hook and the TypeScript
+governance-gate sidecar, exercising the real-runtime cases the in-TS
+`runtime-gate-enforces-two-phase` probe cannot:
+
+  0. a BARE CALLABLE in the toolset is normalised to a governed FunctionTool (the
+     same `tools=[my_func]` shape `AssistantAgent` accepts);
+  1. govern_tools returns governed wrappers only; a governed L1 call executes
+     through AutoGen's own execution path (`StaticWorkbench.call_tool`, the exact
+     dispatch an `AssistantAgent` uses) — the body runs exactly once, remoted back;
+  2. a custom step invokes a governed tool via ``governed_call`` (incl. the
+     normalised bare-callable tool);
+  3. an async-implemented AutoGen tool (an async ``FunctionTool``) runs through the
+     gate's remoted execute, and a custom ``BaseTool`` subclass works too; the
+     remoted body runs on ONE stable persistent loop, so a tool's loop-scoped state
+     survives across calls (3c);
+  4. concurrent in-flight calls are correlated to the right result;
+  5. an L4 tool is HELD (two-phase across the boundary): with no approver it
+     times out and the body NEVER runs — both through ``governed_call`` (raises)
+     and through the framework path (``call_tool`` surfaces an error ``ToolResult``);
+  6. a tool that was never registered is DENIED — fail closed;
+  7. the governed wrappers are valid AutoGen ``BaseTool``s the framework accepts —
+     they attach to a real ``AssistantAgent`` (a stub model client, no LLM/key);
+  8. a non-finite float in an argument or a result fails the call rather than
+     hanging it (Python's json would otherwise emit invalid ``NaN``);
+  9. an already-cancelled ``CancellationToken`` short-circuits the wrapper — no
+     action is proposed and the body never runs.
+
+Spawns the gate via ``bun run <repo>/packages/cli/src/index.ts runtime gate``.
+Invoked by the runtime-gated ``autogen-tool-calls-are-governed`` probe, which skips
+loudly when Python / AutoGen is absent. Exit 0 = pass, 1 = fail.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import math
+import sys
+import tempfile
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+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/autogen) 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_autogen 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" / "autogen"))
+    from lodestar_autogen import (  # noqa: E402
+        GateClient,
+        GateError,
+        LodestarDenied,
+        govern_tools,
+        governed_call,
+    )
+
+try:
+    from autogen_core import CancellationToken
+    from autogen_core.models import ChatCompletionClient, RequestUsage
+    from autogen_core.tools import BaseTool, FunctionTool, StaticWorkbench
+    from autogen_agentchat.agents import AssistantAgent
+    from pydantic import BaseModel, Field
+except Exception as exc:  # pragma: no cover - the probe gates on import availability
+    print(f"SKIP: AutoGen 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, "search": 0, "loop_check": 0}
+
+
+def echo(msg: str) -> dict:
+    """echo a message back"""
+    runs["echo"] += 1
+    return {"echo": msg}
+
+
+def search(q: str) -> dict:
+    """search the web (a BARE CALLABLE — not a BaseTool; govern_tools must
+    normalise it to a FunctionTool the way AssistantAgent does)"""
+    runs["search"] += 1
+    return {"hits": [q]}
+
+
+# Records the running loop across calls to prove the remoted body runs on ONE
+# stable persistent loop (a fresh asyncio.run per call would give a new, torn-down
+# loop each time → cross-loop breakage for loop-scoped state).
+_loop_state: dict[str, object] = {"loop": None}
+
+
+async def loop_check(x: int) -> dict:
+    """async tool that reports whether it is running on the same loop as last call"""
+    runs["loop_check"] += 1
+    current = asyncio.get_running_loop()
+    same = _loop_state["loop"] is current
+    _loop_state["loop"] = current
+    return {"same_as_prev": same}
+
+
+def deploy(target: str) -> dict:
+    """deploy to a target (irreversible, L4)"""
+    runs["deploy"] += 1  # must stay 0 for a held L4 with no approver
+    return {"deployed": target}
+
+
+async def fetch(url: str) -> dict:
+    """fetch a url (async-implemented tool)"""
+    runs["fetch"] += 1
+    return {"fetched": url}
+
+
+def nan_out(x: int) -> dict:
+    """returns a non-finite float (invalid JSON for the gate)"""
+    # The hook must reject this (→ tool_error → failed action), never emit `NaN`.
+    return {"output": {"value": float("nan")}}
+
+
+class ReadDocArgs(BaseModel):
+    path: str = Field(..., description="path to read")
+
+
+class ReadDoc(BaseTool):  # type: ignore[type-arg]
+    """A custom BaseTool subclass (async run) that surfaces untrusted content."""
+
+    def __init__(self) -> None:
+        super().__init__(args_type=ReadDocArgs, return_type=dict, name="read_doc", description="read an (untrusted) document")
+
+    async def run(self, args: ReadDocArgs, cancellation_token: CancellationToken) -> dict:
+        runs["read_doc"] += 1
+        # Surface untrusted document content for external_document evidence.
+        return {"output": {"read": args.path}, "_lodestar_documents": [{"text": "untrusted file body", "source": args.path}]}
+
+
+# A no-network stub model client so a real AssistantAgent can be constructed
+# (construction validates the toolset); we never run inference.
+class _StubModelClient(ChatCompletionClient):  # type: ignore[misc]
+    @property
+    def model_info(self) -> dict:
+        return {
+            "vision": False,
+            "function_calling": True,
+            "json_output": False,
+            "family": "unknown",
+            "structured_output": False,
+            "multiple_system_messages": True,
+        }
+
+    @property
+    def capabilities(self) -> dict:
+        return self.model_info
+
+    async def create(self, *a: Any, **k: Any) -> Any:
+        raise NotImplementedError("stub model client: no inference in the e2e")
+
+    def create_stream(self, *a: Any, **k: Any) -> Any:
+        raise NotImplementedError("stub model client: no inference in the e2e")
+
+    async def close(self) -> None:
+        return None
+
+    def actual_usage(self) -> RequestUsage:
+        return RequestUsage(prompt_tokens=0, completion_tokens=0)
+
+    def total_usage(self) -> RequestUsage:
+        return RequestUsage(prompt_tokens=0, completion_tokens=0)
+
+    def count_tokens(self, messages: Any, *, tools: Any = []) -> int:
+        return 0
+
+    def remaining_tokens(self, messages: Any, *, tools: Any = []) -> int:
+        return 0
+
+
+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 call_tool_sync(workbench: Any, name: str, args: dict) -> Any:
+    """Drive a tool through AutoGen's real dispatch path (the agent uses this)."""
+    return asyncio.run(workbench.call_tool(name, args, CancellationToken()))
+
+
+def main() -> int:
+    with tempfile.TemporaryDirectory() as tmp:
+        log_root = str(Path(tmp) / "events")
+        config = {
+            "project_id": "autogen-e2e",
+            "actor_id": "autogen-agent",
+            "session_id": "auto",
+            "log_root": log_root,
+            "default_scope": {"level": "session", "identifier": "autogen-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"},
+                "search": {"required_trust_level": 1, "reversibility": "reversible", "sandbox": "read", "permissions": [], "blast_radius": "session"},
+                "loop_check": {"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("autogen-tool-calls-are-governed (real AutoGen tools + hook + gate)")
+            print("─" * 72)
+
+            echo_t = FunctionTool(echo, description="echo a message back", name="echo")
+            deploy_t = FunctionTool(deploy, description="deploy to a target (irreversible, L4)", name="deploy")
+            fetch_t = FunctionTool(fetch, description="fetch a url (async-implemented tool)", name="fetch")
+            nan_t = FunctionTool(nan_out, description="returns a non-finite float", name="nan_out")
+            read_doc_t = ReadDoc()
+            loop_check_t = FunctionTool(loop_check, description="reports its running loop", name="loop_check")
+            # `search` is a BARE CALLABLE (not pre-wrapped) — govern_tools must
+            # normalise it, exactly as AssistantAgent would.
+            tools = [echo_t, read_doc_t, deploy_t, fetch_t, nan_t, loop_check_t, search]
+
+            governed = govern_tools(gate, tools, hold_wait_ms=2_000)
+            governed_by_name = {t.name: t for t in governed}
+            expected_names = {"echo", "read_doc", "deploy", "fetch", "nan_out", "loop_check", "search"}
+            check("0: only governed wrappers are exposed", set(governed_by_name) == expected_names, str(set(governed_by_name)))
+            # The wrappers are real AutoGen BaseTools (not the originals).
+            check("0: wrappers are BaseTool instances, distinct from the originals", all(isinstance(t, BaseTool) for t in governed) and governed_by_name["echo"] is not echo_t, "")
+            # The original schema is preserved (the model sees the right parameters).
+            check("0: governed echo preserves the original schema", list(governed_by_name["echo"].schema["parameters"]["properties"]) == ["msg"], str(governed_by_name["echo"].schema["parameters"]["properties"]))
+            # A bare callable was accepted and normalised to a governed FunctionTool.
+            check("0: bare callable was normalised + governed (search)", isinstance(governed_by_name.get("search"), BaseTool) and list(governed_by_name["search"].schema["parameters"]["properties"]) == ["q"], str(governed_by_name.get("search") and governed_by_name["search"].schema["parameters"]["properties"]))
+
+            # The governed wrappers dispatch through AutoGen's REAL execution path:
+            # StaticWorkbench.call_tool → tool.run_json → the gate.
+            wb = StaticWorkbench(governed)
+
+            # 1. a governed L1 tool runs through the workbench; the body runs once,
+            #    remoted back. call_tool returns a (stringified) ToolResult.
+            r = call_tool_sync(wb, "echo", {"msg": "hi"})
+            check("1: StaticWorkbench.call_tool ran the governed echo", (not r.is_error) and json.loads(r.result[0].content) == {"echo": "hi"}, str(r.result[0].content))
+            check("1: echo body ran exactly once", runs["echo"] == 1, str(runs["echo"]))
+
+            # 2. custom step via governed_call (returns the structured output).
+            res = governed_call(gate, "echo", {"msg": "from-step"})
+            check("2: governed_call returned the tool output", res == {"echo": "from-step"}, str(res))
+            check("2: echo body ran again exactly once", runs["echo"] == 2, str(runs["echo"]))
+
+            # 2b. a custom BaseTool subclass with an async run, surfacing untrusted
+            #     document content, runs through the gate's remoted execute.
+            doc = governed_call(gate, "read_doc", {"path": "/notes.md"})
+            check("2b: custom BaseTool subclass ran via the gate", doc == {"read": "/notes.md"}, str(doc))
+            check("2b: read_doc body ran once", runs["read_doc"] == 1, str(runs["read_doc"]))
+
+            # 2c. the normalised bare-callable tool runs through the gate.
+            hits = governed_call(gate, "search", {"q": "lodestar"})
+            check("2c: normalised bare-callable tool ran via the gate", hits == {"hits": ["lodestar"]}, str(hits))
+            check("2c: search body ran once", runs["search"] == 1, str(runs["search"]))
+
+            # 3. an async-implemented tool runs via the gate's remoted execute (the
+            #    hook drives its coroutine with asyncio.run on the worker thread),
+            #    through BOTH the framework path and a direct governed_call.
+            afetch = call_tool_sync(wb, "fetch", {"url": "https://x"})
+            check("3: async tool ran via StaticWorkbench.call_tool", (not afetch.is_error) and json.loads(afetch.result[0].content) == {"fetched": "https://x"}, str(afetch.result[0].content))
+            res_async = governed_call(gate, "fetch", {"url": "https://y"})
+            check("3: async tool ran via governed_call", res_async == {"fetched": "https://y"}, str(res_async))
+            check("3: async tool body ran exactly twice", runs["fetch"] == 2, str(runs["fetch"]))
+
+            # 3c. the remoted body runs on ONE stable persistent loop, so a tool's
+            #     loop-scoped state survives across calls (a fresh asyncio.run per
+            #     call would give a new, torn-down loop each time → cross-loop break).
+            first = governed_call(gate, "loop_check", {"x": 1})
+            second = governed_call(gate, "loop_check", {"x": 2})
+            check("3c: first loop_check sees no previous loop", first == {"same_as_prev": False}, str(first))
+            check("3c: second loop_check runs on the SAME persistent loop", second == {"same_as_prev": True}, str(second))
+
+            # 4. concurrent in-flight calls are each correlated to their own result.
+            before = runs["echo"]
+            results: dict[str, object] = {}
+            errors: list[str] = []
+
+            def call(tag: str) -> None:
+                try:
+                    results[tag] = governed_call(gate, "echo", {"msg": tag})
+                except Exception as exc:  # noqa: BLE001
+                    errors.append(f"{tag}: {exc}")
+
+            threads = [threading.Thread(target=call, args=(f"C{i}",)) for i in range(4)]
+            for t in threads:
+                t.start()
+            for t in threads:
+                t.join()
+            check("4: concurrent calls all returned", len(results) == 4 and not errors, f"{results} errs={errors}")
+            check("4: each concurrent call correlated to its own arg", all(results.get(f"C{i}") == {"echo": f"C{i}"} for i in range(4)), str(results))
+            check("4: all concurrent bodies ran", runs["echo"] - before == 4, 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))
+            # Through the framework path, the workbench catches the denial and
+            # surfaces it as an error ToolResult (re-plannable for the agent).
+            framework = call_tool_sync(wb, "deploy", {"target": "prod2"})
+            check("5: held L4 surfaces as an error ToolResult via call_tool", framework.is_error and "approval" in framework.result[0].content.lower(), str(framework.result[0].content))
+            check("5: deploy body STILL never ran", 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))
+
+            # 9. an already-cancelled CancellationToken short-circuits the wrapper:
+            #    no action is proposed and the body never runs, so a cancelled agent
+            #    run starts no new governed work. (The remoted body, once in the
+            #    gate's execute phase, runs server-side and isn't force-cancellable
+            #    across the RPC boundary — a documented boundary, ADR-0027 §2.)
+            echo_before = runs["echo"]
+            cancelled = False
+            ct = CancellationToken()
+            ct.cancel()
+            try:
+                asyncio.run(governed_by_name["echo"].run_json({"msg": "nope"}, ct))
+            except asyncio.CancelledError:
+                cancelled = True
+            check("9: a pre-cancelled token short-circuits (CancelledError)", cancelled, str(cancelled))
+            check("9: echo body did NOT run on a cancelled token", runs["echo"] == echo_before, str(runs["echo"] - echo_before))
+
+            # 7. the governed wrappers are valid AutoGen tools the framework accepts:
+            #    they attach to a real AssistantAgent (construction validates the
+            #    toolset; a stub model client means no LLM call / API key needed).
+            agent_ok = None
+            try:
+                agent = AssistantAgent("ops", model_client=_StubModelClient(), tools=governed)
+                agent_ok = {t.name for t in agent._tools} == expected_names
+            except Exception as exc:  # noqa: BLE001
+                agent_ok = False
+                print(f"      (AssistantAgent construction raised: {exc})")
+            check("7: governed wrappers attach to a real AssistantAgent", agent_ok is True, str(agent_ok))
+
+            # 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.
+            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 — AutoGen native tool calls are governed end-to-end")
+            print("─" * 72)
+            return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())