halo-format-langgraph 0.2.0__tar.gz

halo_format_langgraph-0.2.0/.gitignore

@@ -0,0 +1,41 @@
+# Node / TypeScript
+node_modules/
+dist/
+*.tsbuildinfo
+.npm/
+pnpm-debug.log*
+npm-debug.log*
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+*.whl
+.venv/
+venv/
+.uv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Coverage / test output
+coverage/
+.coverage
+htmlcov/
+
+# Release: Python distributions built in CI before the PyPI upload
+dist-python/
+
+# Editor / OS
+.DS_Store
+.idea/
+*.swp
+
+# Local env
+.env
+.env.local
+
+# Internal design docs — never commit
+private/

halo_format_langgraph-0.2.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: halo-format-langgraph
+Version: 0.2.0
+Summary: Halo host adapter for LangChain agents and LangGraph graphs (Python): a wrap_tool_call encode middleware plus a halo_fetch navigation tool. install_halo() wires it in one call.
+Project-URL: Homepage, https://github.com/halo-format/halo
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: halo-format
+Requires-Dist: langchain-core>=1.0
+Requires-Dist: langchain>=1.0
+Provides-Extra: langgraph
+Requires-Dist: langgraph; extra == 'langgraph'
+Description-Content-Type: text/markdown
+
+# halo-format-langgraph
+
+Halo host adapter for [LangChain](https://github.com/langchain-ai/langchain) agents and
+[LangGraph](https://github.com/langchain-ai/langgraph) graphs (Python). `install_halo()` wires it in
+one call:
+
+- a **`wrap_tool_call` encode middleware** — the deterministic wrap-the-tool-call hook, LangChain's
+  analog of the Claude SDK's PostToolUse — that replaces a large tool result with a halo **shape map**
+  (root kind + one line per field: ref, kind, and a bounded preview), so the payload stays out of the
+  model's context while it still sees what's there. The full envelope rides in the `ToolMessage`
+  **`artifact`** (kept in graph state, never sent to the model) for audit/replay;
+- a single plain LangChain **`halo_fetch`** tool the model uses to pull back only the leaves it needs,
+  verified on read — a ref that lands on a branch returns that branch's sub-refs, so one batch API both
+  pulls and expands (there is no separate `halo_walk`).
+
+```python
+from langchain.agents import create_agent
+from halo_format_langgraph import install_halo
+
+result = install_halo(tools=my_tools)
+agent = create_agent(model, tools=result.tools, middleware=result.middleware)
+# result.session holds the shared store for audit/inspection
+```
+
+For hand-built `StateGraph`s, use `halo_tool_node(tools=...)` instead — it returns a `ToolNode` with the
+same wrapper attached as `wrap_tool_call` / `awrap_tool_call`, plus the tools list (to bind to your
+model) and the session.
+
+The middleware is deterministic plumbing (it always fires, for every tool); the Halo Skill (or
+prompt-mode guidance) is the navigation behavior. Pass `store=FileStore(dir)` for the heavy/persistent
+deployment. The core engine is [`halo-format`](https://pypi.org/project/halo-format/); this package is
+only the shim.

halo_format_langgraph-0.2.0/README.md

@@ -0,0 +1,32 @@
+# halo-format-langgraph
+
+Halo host adapter for [LangChain](https://github.com/langchain-ai/langchain) agents and
+[LangGraph](https://github.com/langchain-ai/langgraph) graphs (Python). `install_halo()` wires it in
+one call:
+
+- a **`wrap_tool_call` encode middleware** — the deterministic wrap-the-tool-call hook, LangChain's
+  analog of the Claude SDK's PostToolUse — that replaces a large tool result with a halo **shape map**
+  (root kind + one line per field: ref, kind, and a bounded preview), so the payload stays out of the
+  model's context while it still sees what's there. The full envelope rides in the `ToolMessage`
+  **`artifact`** (kept in graph state, never sent to the model) for audit/replay;
+- a single plain LangChain **`halo_fetch`** tool the model uses to pull back only the leaves it needs,
+  verified on read — a ref that lands on a branch returns that branch's sub-refs, so one batch API both
+  pulls and expands (there is no separate `halo_walk`).
+
+```python
+from langchain.agents import create_agent
+from halo_format_langgraph import install_halo
+
+result = install_halo(tools=my_tools)
+agent = create_agent(model, tools=result.tools, middleware=result.middleware)
+# result.session holds the shared store for audit/inspection
+```
+
+For hand-built `StateGraph`s, use `halo_tool_node(tools=...)` instead — it returns a `ToolNode` with the
+same wrapper attached as `wrap_tool_call` / `awrap_tool_call`, plus the tools list (to bind to your
+model) and the session.
+
+The middleware is deterministic plumbing (it always fires, for every tool); the Halo Skill (or
+prompt-mode guidance) is the navigation behavior. Pass `store=FileStore(dir)` for the heavy/persistent
+deployment. The core engine is [`halo-format`](https://pypi.org/project/halo-format/); this package is
+only the shim.

halo_format_langgraph-0.2.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "halo-format-langgraph"
+version = "0.2.0"
+description = "Halo host adapter for LangChain agents and LangGraph graphs (Python): a wrap_tool_call encode middleware plus a halo_fetch navigation tool. install_halo() wires it in one call."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+# The adapter is a separate opt-in package; depending on the host framework the consumer already has is
+# correct. The "lightest install" principle is about the core (halo-format), which stays zero-dep.
+# langgraph is needed only for the halo_tool_node() path and is imported lazily there.
+dependencies = ["halo-format", "langchain>=1.0", "langchain-core>=1.0"]
+
+[project.optional-dependencies]
+langgraph = ["langgraph"]
+
+[project.urls]
+Homepage = "https://github.com/halo-format/halo"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/halo_format_langgraph"]
+
+[tool.uv.sources]
+halo-format = { workspace = true }

halo_format_langgraph-0.2.0/src/halo_format_langgraph/__init__.py

@@ -0,0 +1,132 @@
+"""halo_format_langgraph — Halo host adapter for LangChain agents and LangGraph graphs (Python).
+
+The interception point is LangChain's ``wrap_tool_call`` — a deterministic wrap-the-tool-call hook, the
+direct analog of the Claude Agent SDK's PostToolUse. Above a size threshold it encodes a tool result
+into a shared store and rewrites the ToolMessage the model sees: ``content`` becomes a SHAPE MAP (not the
+blob), and the full envelope rides in ``artifact`` (kept in graph state, never sent to the model). One
+plain LangChain tool, ``halo_fetch(refs)``, backed by the same store, lets the model pull back the
+withheld leaves (and expand branches), verified on read.
+
+Two attach surfaces, one wrapper body:
+
+  - ``install_halo(tools=..., middleware=...)`` — the primary path. Returns the augmented ``tools`` and
+    ``middleware`` lists to splice into ``create_agent`` (plus the shared session). The Halo middleware
+    is a ``HaloMiddleware`` (an ``AgentMiddleware`` subclass) providing both sync and async wrap.
+  - ``halo_tool_node(tools=...)`` — for hand-built ``StateGraph``s. Returns a ``ToolNode`` with the same
+    wrapper attached as ``wrap_tool_call`` / ``awrap_tool_call`` (plus the tools list and session).
+
+MANDATORY correctness rule: the middleware must NOT re-encode the navigation tool's own output, or a
+fetched leaf would be replaced by a new map and the model would never see the value. Enforced by an
+``is_halo_nav_tool`` name check at the top of the wrapper.
+
+Light vs. heavy (integration doc, Section 7): pass ``store=FileStore(dir)`` for cross-process
+persistence, and wrap navigation with the L2 chain, without touching the control flow here."""
+
+from typing import NamedTuple, Optional
+
+from .accumulate import KeyOf, arg_join
+from .constants import HALO_FETCH_TOOL, is_halo_nav_tool
+from .middleware import (
+    HaloMiddleware,
+    make_async_wrapper,
+    make_sync_wrapper,
+)
+from .nav_tool import create_halo_fetch_tool, halo_fetch
+from .serialize import parse_tool_output, preview_of, serialize_envelope, shape_of, size_of
+from .session import HaloSession
+
+
+class InstallHaloResult(NamedTuple):
+    tools: list  # your tools + halo_fetch, to pass to create_agent(tools=...)
+    middleware: list  # your middleware + HaloMiddleware, to pass to create_agent(middleware=...)
+    session: HaloSession  # the shared session (store + map registry), for audit swaps / inspection
+
+
+class HaloToolNodeResult(NamedTuple):
+    tool_node: object  # a langgraph ToolNode with the Halo wrapper attached
+    tools: list  # your tools + halo_fetch, to bind to the model so it can call halo_fetch
+    session: HaloSession
+
+
+def _make_session(store, key_of, alg, now, session) -> HaloSession:
+    return session if session is not None else HaloSession(
+        store=store, key_of=key_of, alg=alg, now=now
+    )
+
+
+def install_halo(
+    *,
+    tools: Optional[list] = None,
+    middleware: Optional[list] = None,
+    threshold: int = 2048,
+    store=None,
+    key_of: Optional[KeyOf] = None,
+    alg: str = "sha256",
+    now=None,
+    session: Optional[HaloSession] = None,
+) -> InstallHaloResult:
+    """Wire the Halo adapter into a ``create_agent`` setup. Append the returned ``tools`` and
+    ``middleware`` to the call:
+
+        result = install_halo(tools=my_tools)
+        agent = create_agent(model, tools=result.tools, middleware=result.middleware)
+    """
+    session = _make_session(store, key_of, alg, now, session)
+    mw = HaloMiddleware(session, threshold)
+    fetch_tool = create_halo_fetch_tool(session)
+    return InstallHaloResult(
+        tools=[*(tools or []), fetch_tool],
+        middleware=[*(middleware or []), mw],
+        session=session,
+    )
+
+
+def halo_tool_node(
+    tools: Optional[list] = None,
+    *,
+    threshold: int = 2048,
+    store=None,
+    key_of: Optional[KeyOf] = None,
+    alg: str = "sha256",
+    now=None,
+    session: Optional[HaloSession] = None,
+) -> HaloToolNodeResult:
+    """Build a LangGraph ``ToolNode`` with the Halo wrapper attached, for hand-built ``StateGraph``s.
+
+    Returns the node, the tools list (yours + ``halo_fetch``, to bind to the model), and the session.
+    Import is deferred so that ``langgraph`` is only required for this path, not for ``install_halo``.
+    """
+    from langgraph.prebuilt import ToolNode
+
+    session = _make_session(store, key_of, alg, now, session)
+    fetch_tool = create_halo_fetch_tool(session)
+    all_tools = [*(tools or []), fetch_tool]
+    node = ToolNode(
+        all_tools,
+        wrap_tool_call=make_sync_wrapper(session, threshold),
+        awrap_tool_call=make_async_wrapper(session, threshold),
+    )
+    return HaloToolNodeResult(tool_node=node, tools=all_tools, session=session)
+
+
+__all__ = [
+    "install_halo",
+    "InstallHaloResult",
+    "halo_tool_node",
+    "HaloToolNodeResult",
+    "HaloMiddleware",
+    "make_sync_wrapper",
+    "make_async_wrapper",
+    "create_halo_fetch_tool",
+    "halo_fetch",
+    "HaloSession",
+    "arg_join",
+    "KeyOf",
+    "size_of",
+    "parse_tool_output",
+    "serialize_envelope",
+    "shape_of",
+    "preview_of",
+    "HALO_FETCH_TOOL",
+    "is_halo_nav_tool",
+]

halo_format_langgraph-0.2.0/src/halo_format_langgraph/accumulate.py

@@ -0,0 +1,55 @@
+"""Entity accumulation policy: which calls fold into one growing map (SDK architecture, Section 9.1).
+
+key_of(tool_name, tool_input) returns an entity key, or None to give the call its own fresh map. The
+default, arg_join, keys on the first scalar argument value, so normalized REST detail calls about one
+entity group together: get_customer({"id": 123}) and get_appointments({"customer_id": 123}) both key
+on 123 and fold into one map, while search({"query": "smith"}) keys on "smith" and stays its own list
+map until the first detail call. It keys on the argument VALUE, not the field name or any result id,
+which is what lets a list result land under the entity instead of fragmenting.
+
+arg_join's one real gap is value collision across entity types (customer 123 vs invoice 123, both
+passing 123). That is the single thing a generic heuristic cannot resolve alone; supply a domain
+key_of (e.g. one that prefixes the resource type) when it matters, as it usually does for money or
+medical data."""
+
+from typing import Callable, Optional
+
+KeyOf = Callable[[str, object], Optional[str]]
+
+# A short scalar (number, or string up to this many chars) is treated as an id-like argument worth
+# grouping on. Longer strings are typically free text (a query, a body) and are skipped.
+_MAX_KEY_STRING_LENGTH = 128
+
+
+def _scalar_key(value) -> Optional[str]:
+    # bool is an int subclass in Python; exclude it explicitly (a flag is not an id).
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, str) and 0 < len(value) <= _MAX_KEY_STRING_LENGTH:
+        return value
+    return None
+
+
+def arg_join(tool_name: str, tool_input: object) -> Optional[str]:
+    """Default policy: group by the first scalar argument value.
+
+    Dicts are scanned in insertion order, lists in index order; a bare scalar input is its own key.
+    Returns None when no scalar argument is present (e.g. a no-arg call), so that call gets a fresh
+    synthetic map id.
+    """
+    direct = _scalar_key(tool_input)
+    if direct is not None:
+        return direct
+    if isinstance(tool_input, dict):
+        for value in tool_input.values():
+            k = _scalar_key(value)
+            if k is not None:
+                return k
+    elif isinstance(tool_input, (list, tuple)):
+        for item in tool_input:
+            k = _scalar_key(item)
+            if k is not None:
+                return k
+    return None

halo_format_langgraph-0.2.0/src/halo_format_langgraph/constants.py

@@ -0,0 +1,16 @@
+"""The one name shared between the middleware (which must exclude it) and the navigation tool (which
+defines it). Kept in one place so the exclusion and the registration can never drift apart.
+
+Unlike the Claude adapter, the navigation tool here is a plain LangChain tool, not an in-process MCP
+server, so its name has no ``mcp__<server>__`` prefix — it is simply ``halo_fetch`` and the exclusion
+is a single string comparison."""
+
+# One navigation tool only. halo_fetch is the single batch API the model ever sees: it pulls leaves
+# AND, when a ref lands on a branch, returns that branch's sub-shape — so there is no second tool
+# (no halo_walk) to choose between or confuse a leaf ref with.
+HALO_FETCH_TOOL = "halo_fetch"
+
+
+def is_halo_nav_tool(tool_name: str) -> bool:
+    """True for the adapter's own navigation tool — the result the middleware must NOT re-encode."""
+    return tool_name == HALO_FETCH_TOOL

halo_format_langgraph-0.2.0/src/halo_format_langgraph/middleware.py

@@ -0,0 +1,102 @@
+"""The encode middleware — the plumbing. It wraps every tool call: it runs the tool via the handler,
+and above a size threshold rewrites the resulting ToolMessage so the model sees a SHAPE MAP instead of
+the blob, while the full payload goes to the store and the full envelope rides in ``ToolMessage.artifact``
+(kept in graph state, never serialized into the model's context). This is deterministic and
+model-independent: the payload is out of context before the model is involved, so the model cannot leak
+a full result by forgetting to navigate.
+
+The same wrapper body drives two LangChain/LangGraph surfaces, which share one ``ToolCallWrapper`` shape
+``(request, handler/execute) -> ToolMessage | Command``:
+
+  - ``create_agent(middleware=[...])`` — via the ``HaloMiddleware`` subclass below (the primary path);
+  - ``ToolNode(wrap_tool_call=..., awrap_tool_call=...)`` — via the bare functions, for hand-built graphs.
+
+Two passthrough conditions, in order (mirrors the Claude encode hook):
+  1. The tool IS the halo navigation tool. MANDATORY: re-encoding a fetched leaf would replace it with
+     a new map and the model would never receive the value.
+  2. The ToolMessage content is below the size threshold, or is not JSON-ish — pass through untouched.
+
+A non-``ToolMessage`` return (a ``Command`` that updates graph state directly) always passes through:
+there is nothing to encode.
+
+The session underneath is SYNC (port convention); only the async surface awaits the handler."""
+
+from langchain.agents.middleware import AgentMiddleware
+from langchain_core.messages import ToolMessage
+
+from .constants import is_halo_nav_tool
+from .serialize import parse_tool_output, serialize_envelope, size_of
+
+_DEFAULT_THRESHOLD = 2048
+
+# Where an upstream tool's own artifact is preserved if Halo needs the slot for its envelope, so a
+# tool that already used content_and_artifact does not silently lose its data.
+_PRIOR_ARTIFACT_KEY = "halo_prior_artifact"
+
+
+def _rewrite(session, threshold: int, msg, request):
+    """Encode a tool's ToolMessage and return a rewritten copy: content -> shape map, artifact ->
+    envelope. Returns the message untouched when it should pass through. Builds a copy via
+    ``model_copy`` rather than mutating in place, so a handler that returns a shared/cached message is
+    never clobbered (the safe path — the handler's tool_call_id, name and status are preserved)."""
+    if not isinstance(msg, ToolMessage):
+        return msg  # a Command (state update) or other return — nothing to encode
+    if size_of(msg.content) < threshold:
+        return msg
+    value = parse_tool_output(msg.content)
+    if value is None:
+        return msg
+
+    tool_call = request.tool_call
+    result = session.ingest(tool_call["name"], tool_call.get("args"), value)
+    hints = session.describe(result["envelope"])
+
+    update = {
+        "content": serialize_envelope(result["envelope"], hints),  # the SHAPE MAP (model-visible)
+        "artifact": result["envelope"],  # full envelope (out of context, persisted in state)
+    }
+    if msg.artifact is not None:
+        # Preserve an upstream content_and_artifact tool's own artifact rather than dropping it.
+        update["additional_kwargs"] = {
+            **(msg.additional_kwargs or {}),
+            _PRIOR_ARTIFACT_KEY: msg.artifact,
+        }
+    return msg.model_copy(update=update)
+
+
+def make_sync_wrapper(session, threshold: int = _DEFAULT_THRESHOLD):
+    """The sync ToolCallWrapper for ToolNode(wrap_tool_call=...) and the middleware's sync path."""
+
+    def wrapper(request, handler):
+        if is_halo_nav_tool(request.tool_call["name"]):
+            return handler(request)  # MANDATORY: never re-encode a fetched leaf
+        return _rewrite(session, threshold, handler(request), request)
+
+    return wrapper
+
+
+def make_async_wrapper(session, threshold: int = _DEFAULT_THRESHOLD):
+    """The async ToolCallWrapper for ToolNode(awrap_tool_call=...) and the middleware's async path."""
+
+    async def wrapper(request, handler):
+        if is_halo_nav_tool(request.tool_call["name"]):
+            return await handler(request)
+        return _rewrite(session, threshold, await handler(request), request)
+
+    return wrapper
+
+
+class HaloMiddleware(AgentMiddleware):
+    """The create_agent middleware. Provides both ``wrap_tool_call`` and ``awrap_tool_call`` over one
+    shared wrapper body, so the adapter works under both ``agent.invoke`` and ``agent.ainvoke``."""
+
+    def __init__(self, session, threshold: int = _DEFAULT_THRESHOLD):
+        super().__init__()
+        self._sync = make_sync_wrapper(session, threshold)
+        self._async = make_async_wrapper(session, threshold)
+
+    def wrap_tool_call(self, request, handler):
+        return self._sync(request, handler)
+
+    async def awrap_tool_call(self, request, handler):
+        return await self._async(request, handler)

halo_format_langgraph-0.2.0/src/halo_format_langgraph/nav_tool.py

@@ -0,0 +1,50 @@
+"""The navigation surface — how the model pulls back what the middleware withheld. A single plain
+LangChain tool, ``halo_fetch``, backed by the session store and verified on read. No MCP server: it is
+an ordinary tool, appended to the agent's tools list and bound to the model like any other.
+
+One tool on purpose: an earlier design (in the Claude adapter's history) also exposed halo_walk and the
+model wasted turns choosing between them and fetching a branch ref through the leaf tool. halo_fetch now
+does both — a leaf ref returns its value, a branch ref returns its sub-shape — so there is a single
+batch API and nothing to disambiguate.
+
+halo_fetch takes a LIST of refs: each fetch is a separate model round trip, the dominant latency in the
+loop, so the model is nudged to gather every ref a step needs and pull them in one call. It returns a
+per-ref result, so one unknown or tampered entry (surfaced as a HashMismatch) never sinks the batch.
+
+It is declared ``response_format="content_and_artifact"``: the model reads the per-ref values from the
+message content, and the same structured result is attached as the artifact (kept in graph state for
+audit/replay, not re-sent to the model). The pure helper (halo_fetch) is split from the tool wrapping so
+it can be tested without the LangChain runtime."""
+
+import json
+
+from langchain_core.tools import tool
+
+from .constants import HALO_FETCH_TOOL
+
+
+def halo_fetch(session, refs) -> dict:
+    """Fetch several refs at once, verified, with a per-ref result; branch refs return their sub-shape."""
+    return session.fetch(refs)
+
+
+_FETCH_DESC = (
+    "The one tool for reading a halo map. Pass ALL the refs a step needs in one call (refs is a list) "
+    "rather than one at a time — each call is a separate round trip. A ref like `m1.income` (or a raw "
+    "`h:` handle) that points at a value returns it as {ok:true,value}; a ref that points at a "
+    "[branch] returns {ok:true,kind:'branch',fields:[…]} listing its sub-refs to fetch next. An entry "
+    "with ok=false (e.g. HashMismatch) means that data must not be trusted."
+)
+
+
+def create_halo_fetch_tool(session):
+    """Build the single ``halo_fetch`` LangChain tool over the given session."""
+
+    @tool(HALO_FETCH_TOOL, description=_FETCH_DESC, response_format="content_and_artifact")
+    def _halo_fetch(refs: list[str]):
+        results = halo_fetch(session, refs)
+        # content: the JSON the model reads (the fetched values / branch sub-shapes).
+        # artifact: the same structured result, kept in graph state for audit/replay.
+        return json.dumps(results), results
+
+    return _halo_fetch

halo_format_langgraph-0.2.0/src/halo_format_langgraph/serialize.py

@@ -0,0 +1,182 @@
+"""Serialization at the SDK boundary: measure a raw tool result, parse it into a JSON value the
+core can encode, and serialize a halo envelope back into the string the model sees.
+
+updatedToolOutput carries the tool's visible output. What the model sees in place of the blob is a
+SHAPE MAP, not the raw envelope: the root kind stated up front, then one line per field giving its
+ref, its kind (leaf vs ``[branch]``), and a bounded preview. This is deliberately not the hashed
+envelope JSON — the 64-char branch handles are dead weight to the model (it navigates by
+``<mapId>.<field>`` refs, which the session's navigator resolves from its own registry), and showing
+only names without kinds is exactly what made the model guess the root kind and fetch a branch as if
+it were a leaf. The hints close both gaps. The envelope object itself is unchanged and still held
+verbatim in the session for verified reads."""
+
+import json
+
+# A per-field descriptor (a plain dict ``{"ref", "kind", "shape", "preview"}``) the model sees in the
+# shape map. ``shape`` is a short structural tag ("number", "string[42]", "object{4}",
+# "[branch] object{7}"); ``preview`` is a bounded sample of a leaf's value, or a branch's child names.
+# Built by HaloSession.describe (it needs the store to read each child node); rendered here.
+
+_PREVIEW_MAX = 80
+
+# A tool's raw output is a string, an already-parsed value, or the MCP content-block shape
+# ``{"content": [{"type": "text", "text": ...}]}``.
+
+
+def size_of(raw) -> int:
+    """Byte length of a raw tool output, used for the size threshold. Never raises."""
+    if raw is None:
+        return 0
+    if isinstance(raw, str):
+        return len(raw.encode("utf-8"))
+    try:
+        return len(json.dumps(raw).encode("utf-8"))
+    except (TypeError, ValueError):
+        return 0  # unserializable (e.g. a cycle) — treat as below threshold, pass through
+
+
+def parse_tool_output(raw):
+    """Coerce a raw tool output into a JSON value to encode.
+
+    Strings are parsed as JSON when they look like it and otherwise kept as a string leaf; the MCP
+    ``{"content": [{"text": ...}]}`` block is unwrapped to its concatenated text (parsed when it is
+    itself JSON). Anything already-structured is returned as is. Returns ``None`` when there is
+    nothing meaningful to encode.
+    """
+    if raw is None:
+        return None
+    if isinstance(raw, str):
+        return _parse_maybe_json(raw)
+    # The MCP result may arrive as {"content": [{type:text,text}]} OR as the bare content-block list
+    # [{type:text,text}] (the shape some SDK hosts hand the hook). Unwrap either.
+    if isinstance(raw, (dict, list)):
+        text = _extract_content_text(raw)
+        if text is not None:
+            return _parse_maybe_json(text)
+        return raw
+    return raw  # int | float | bool
+
+
+def _parse_maybe_json(s: str):
+    trimmed = s.strip()
+    if trimmed == "":
+        return s
+    # Only attempt a parse on something that looks like JSON, so plain prose stays a string leaf.
+    if trimmed[0] in "{[\"":
+        try:
+            return json.loads(trimmed)
+        except (json.JSONDecodeError, ValueError):
+            return s
+    return s
+
+
+def _extract_content_text(value):
+    """Unwrap the MCP content-block shape to its text, concatenating text blocks.
+
+    Accepts both the ``{"content": [...]}`` dict and a bare ``[{type:text,text}]`` list. Returns None
+    when the value is not content blocks (a genuine list/dict result), so it is encoded as-is.
+    """
+    if isinstance(value, list):
+        content = value
+    elif isinstance(value, dict) and isinstance(value.get("content"), list):
+        content = value["content"]
+    else:
+        return None
+    texts = [
+        block["text"]
+        for block in content
+        if isinstance(block, dict)
+        and block.get("type") == "text"
+        and isinstance(block.get("text"), str)
+    ]
+    return "".join(texts) if texts else None
+
+
+def shape_of(value) -> str:
+    """A short structural tag for a leaf value: its kind plus a size for strings/lists/objects."""
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, (int, float)):
+        return "number"
+    if isinstance(value, str):
+        return f"string[{len(value)}]"
+    if isinstance(value, list):
+        return f"array[{len(value)}]"
+    return f"object{{{len(value)}}}"
+
+
+def preview_of(value, max_len: int = _PREVIEW_MAX) -> str:
+    """A bounded, single-line JSON sample of a value — enough to recognise it, never the whole payload."""
+    try:
+        s = json.dumps(value, separators=(",", ":"))
+    except (TypeError, ValueError):
+        return ""
+    return s if len(s) <= max_len else f"{s[: max_len - 1]}…"
+
+
+def _is_scalar_shape(shape: str) -> bool:
+    return shape in ("null", "boolean", "number")
+
+
+def _hint_line(hint: dict) -> str:
+    """One field line: ref, structural tag, then the preview/child-names."""
+    preview = hint.get("preview")
+    if preview:
+        eq = "= " if hint["kind"] == "leaf" and _is_scalar_shape(hint["shape"]) else ""
+        tail = f"  {eq}{preview}"
+    else:
+        tail = ""
+    return f'  {hint["ref"]}  {hint["shape"]}{tail}'
+
+
+def _root_shape(names) -> str:
+    """``object, 7 fields`` / ``array, 4 chunks`` for a branch root."""
+    n = len(names)
+    array_like = n > 0 and all(name.isdigit() for name in names)
+    if array_like:
+        return f"array, {n} chunks"
+    return f"object, {n} field{'' if n == 1 else 's'}"
+
+
+def _short_tool(tool: str) -> str:
+    if tool.startswith("mcp__"):
+        parts = tool.split("__", 2)
+        if len(parts) == 3:
+            return parts[2]
+    return tool
+
+
+def serialize_envelope(envelope: dict, hints=None) -> str:
+    """Serialize an envelope into the string the model receives in place of the blob: the map id and
+    root kind stated up front, then (when ``hints`` are supplied) one line per field with its kind and
+    a bounded preview. With no hints it degrades to a bare ref list — still no hashes, still names the
+    root kind, just without the per-field previews the session computes from the store."""
+    source = envelope.get("source") or {}
+    map_id = source.get("id", "?")
+    names = list(envelope["view"]["branches"])
+    is_leaf_root = len(names) == 0
+    if is_leaf_root:
+        root = envelope["view"]["summary"]
+        if root.startswith("leaf:"):
+            root = root[len("leaf:"):].strip()
+    else:
+        root = _root_shape(names)
+    from_ = f" from {_short_tool(source['tool'])}" if source.get("tool") else ""
+
+    head = (
+        f'[halo] map "{map_id}" — {root}{from_}, stored out of context. '
+        "Pull only the fields you need with ONE halo_fetch call — batch every ref into that one call; "
+        "each call is a round trip. A [branch] ref expands to its sub-refs when fetched; every other "
+        "ref returns its value."
+    )
+
+    if is_leaf_root:
+        return f'{head}\nFetch "{map_id}" itself to read the value.'
+
+    if hints:
+        lines = [_hint_line(h) for h in hints]
+    else:
+        lines = [f"  {map_id}.{n}" for n in names]
+    return f"{head}\nFields:\n" + "\n".join(lines)

halo_format_langgraph-0.2.0/src/halo_format_langgraph/session.py

@@ -0,0 +1,196 @@
+"""HaloSession holds the one piece of shared state in the adapter — the store and the per-entity map
+registry — and exposes the three operations the hook and the navigation tools sit on:
+
+    ingest(tool_name, tool_input, value) -> {"envelope", "id"}   (producer; folds into the map)
+    walk(ref)                            -> {"summary", "branches"}
+    fetch(refs)                          -> verified leaves, per-ref
+
+One entity, one map (SDK architecture, Section 9.1): key_of decides which calls share a map id. A
+first call for an id ``encode``s ``{tool: value}``; later calls for the same id ``extend`` that map's
+root with a branch named after the tool, so a customer assembled across several endpoints becomes one
+growing map rather than several fragments. Because extend reuses unchanged child handles and retains
+the prior root, each entity map also carries its own version history for free.
+
+The session is SYNC — it sits on the sync Python core (matching the port convention). Only the thin
+SDK-facing wrappers (the async hook and tool handlers) are async, as the SDK requires.
+
+Every read is verified by the core Navigator, so the store stays untrusted. The Navigator resolves
+map-scoped refs (``m1.income``, ``123.get_appointments``) against the registered envelopes; raw
+handles always work without registration."""
+
+from datetime import datetime, timezone
+from typing import Optional
+
+from halo_format import (
+    HashMismatch,
+    MemoryStore,
+    Navigator,
+    WrongKind,
+    branch_node,
+    build_envelope,
+    decode,
+    derive_summary,
+    hash_bytes,
+    is_branch,
+    is_leaf,
+    serialize,
+)
+from halo_format import encode as _encode
+
+from .accumulate import KeyOf, arg_join
+from .serialize import preview_of, shape_of
+
+_MAX_CHILD_NAMES = 10
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _branch_name(tool_name: str) -> str:
+    """A short branch label for an accumulated tool: strip the ``mcp__<server>__`` prefix."""
+    if tool_name.startswith("mcp__"):
+        parts = tool_name.split("__", 2)
+        if len(parts) == 3:
+            return parts[2]
+    return tool_name
+
+
+class HaloSession:
+    def __init__(self, store=None, key_of: Optional[KeyOf] = None, alg: str = "sha256", now=None):
+        self.store = store if store is not None else MemoryStore()
+        self._key_of = key_of or arg_join
+        self._alg = alg
+        self._now = now or _now_iso
+        self._maps: dict[str, dict] = {}  # id -> latest envelope, for ref resolution + accumulation
+        # id -> {branch_name: subtree_root_handle}: the per-tool trees folded into each entity map.
+        self._entity_tools: dict[str, dict[str, str]] = {}
+        self._navigator: Optional[Navigator] = None  # seeded by the first map, extended via register
+        self._synthetic = 0
+
+    def ingest(self, tool_name: str, tool_input, value) -> dict:
+        """Encode a tool result into the store and return its envelope and map id.
+
+        A map's FIRST result is encoded flat — the value's own fields become the top-level branches,
+        so the model sees them in the envelope and can batch-fetch leaves with no extra walk. Only
+        when a SECOND tool result accumulates into the same entity map (per key_of) do we namespace
+        each tool's tree under its (short) name, since then the field names would otherwise collide.
+        """
+        map_id = self._key_of(tool_name, tool_input)
+        if map_id is None:
+            self._synthetic += 1
+            map_id = f"m{self._synthetic}"
+
+        # Encode the value's own tree once; reuse its root as this tool's subtree under the entity.
+        sub = _encode(value, self.store, alg=self._alg)
+        tools = self._entity_tools.setdefault(map_id, {})
+        tools[_branch_name(tool_name)] = sub["handle"]
+
+        if len(tools) == 1:
+            # Single result: the map IS the value's tree — fields are top-level, no walk needed.
+            envelope = sub["envelope"]
+        else:
+            # Accumulation: namespace each tool's tree under its name (reusing every subtree handle;
+            # only the new root node is stored).
+            branches = dict(tools)
+            root = self.store.put(serialize(branch_node(derive_summary(None, branches), branches)))
+            envelope = build_envelope(root, decode(self.store.get(root)), self._alg)
+
+        # source identifies the map and traces it to the call; it is envelope-only and never hashed.
+        envelope["source"] = {
+            "id": map_id,
+            "tool": tool_name,
+            "args": tool_input,
+            "ts": self._now(),
+        }
+        self._maps[map_id] = envelope
+        self._register(envelope)
+        return {"envelope": envelope, "id": map_id}
+
+    def _register(self, envelope: dict) -> None:
+        if self._navigator is not None:
+            self._navigator.register(envelope)
+        else:
+            self._navigator = Navigator(envelope, self.store)
+
+    def walk(self, ref: str) -> dict:
+        """Verified walk of a branch ref (raw handle or ``mapId.branch[.child]``). Internal — not a tool."""
+        if self._navigator is None:
+            raise RuntimeError("no halo maps in this session yet")
+        return self._navigator.walk(ref)
+
+    def fetch(self, refs) -> dict:
+        """Verified batch fetch — the single navigation surface. Leaves return their value; a ref that
+        lands on a branch returns the branch's sub-shape instead of a WrongKind error, so one tool
+        covers both pulling and expanding. One bad ref never sinks the others (per-ref ok/error)."""
+        if self._navigator is None:
+            return {ref: {"ok": False, "error": "UnknownHandle"} for ref in refs}
+        # The core batch verifies every leaf in one pass; branch refs come back WrongKind, which we
+        # turn into a sub-shape expansion below rather than surfacing as an error.
+        base = self._navigator.fetch_many(refs)
+        out: dict = {}
+        for ref in refs:
+            res = base[ref]
+            if res["ok"]:
+                out[ref] = {"ok": True, "value": res["value"]}
+            elif res.get("error") == "WrongKind":
+                try:
+                    out[ref] = self._expand(ref)
+                except Exception:
+                    out[ref] = res
+            else:
+                out[ref] = res
+        return out
+
+    def describe(self, envelope: dict) -> list:
+        """Describe an envelope's top-level fields for the shape map the model sees: one hint dict per
+        branch, classified (leaf vs branch) and previewed by reading each child node. Sorted by ref so
+        the listing order is deterministic (matching the structural summary's sorted names)."""
+        map_id = (envelope.get("source") or {}).get("id", "")
+        hints = []
+        for name, handle in envelope["view"]["branches"].items():
+            ref = f"{map_id}.{name}" if map_id else name
+            try:
+                hints.append(self._hint_for(ref, handle))
+            except Exception:
+                hints.append({"ref": ref, "kind": "leaf", "shape": "?"})
+        hints.sort(key=lambda h: h["ref"])
+        return hints
+
+    def _expand(self, ref: str) -> dict:
+        """Expand a branch ref into a fetch entry carrying its child refs + hints (the in-fetch
+        fallback so a mis-fetched branch self-corrects in the same call instead of dead-ending)."""
+        handle = self._navigator.resolve(ref)
+        node = self._read(handle)
+        if not is_branch(node):
+            raise WrongKind(f"expand expects a branch: {ref}")
+        fields = [self._hint_for(f"{ref}.{name}", h) for name, h in node["branches"].items()]
+        fields.sort(key=lambda h: h["ref"])
+        return {
+            "ok": True,
+            "kind": "branch",
+            "note": "This ref is a branch, not a value. halo_fetch the leaf refs below to read it.",
+            "fields": fields,
+        }
+
+    def _hint_for(self, ref: str, handle: str) -> dict:
+        """Classify one child handle into a hint dict: a leaf gets its shape + a bounded value preview;
+        a branch gets a ``[branch]`` shape and its child names as the preview (one level, bounded)."""
+        node = self._read(handle)
+        if is_leaf(node):
+            value = node["value"]
+            return {"ref": ref, "kind": "leaf", "shape": shape_of(value), "preview": preview_of(value)}
+        child_names = list(node["branches"])
+        array_like = len(child_names) > 0 and all(n.isdigit() for n in child_names)
+        shape = f"[branch] {'array' if array_like else 'object'}{{{len(child_names)}}}"
+        shown = ", ".join(child_names[:_MAX_CHILD_NAMES])
+        more = ", …" if len(child_names) > _MAX_CHILD_NAMES else ""
+        return {"ref": ref, "kind": "branch", "shape": shape, "preview": f"↳ {shown}{more}"}
+
+    def _read(self, handle: str) -> dict:
+        """A verified read of a handle from the store: re-hash the bytes under the bound alg before
+        decode, so the shape map can never describe substituted bytes. Same check the Navigator makes."""
+        data = self.store.get(handle)
+        if hash_bytes(data, self._alg) != handle:
+            raise HashMismatch(handle)
+        return decode(data)

halo_format_langgraph-0.2.0/tests/test_graph.py

@@ -0,0 +1,70 @@
+"""End-to-end through a real compiled LangGraph: the ToolNode runs the tool, the Halo wrapper rewrites
+the ToolMessage to a shape map, the envelope lands in the artifact, and the session navigates back the
+withheld leaves — verified. Also covers entity accumulation across two calls sharing an argument."""
+
+from langchain_core.messages import AIMessage
+from langchain_core.tools import tool
+from langgraph.graph import END, START, MessagesState, StateGraph
+
+from halo_format_langgraph import halo_tool_node
+
+BIG = {"profile": {"income": {"monthly": 4200}, "debts": {"monthly": 2604}}, "filler": "x" * 3000}
+
+
+@tool
+def bureau_report(applicant: int) -> dict:
+    """Get a bureau report."""
+    return BIG
+
+
+@tool
+def get_appointments(applicant: int) -> dict:
+    """Get appointments for an applicant."""
+    return {"appointments": [{"id": i, "slot": f"2026-06-{i:02d}"} for i in range(1, 30)]}
+
+
+def _graph(tools, **kw):
+    result = halo_tool_node(tools, now=lambda: "T", **kw)
+    g = StateGraph(MessagesState)
+    g.add_node("tools", result.tool_node)
+    g.add_edge(START, "tools")
+    g.add_edge("tools", END)
+    return g.compile(), result.session
+
+
+def _call(name, args, cid):
+    return AIMessage(content="", tool_calls=[{"name": name, "args": args, "id": cid, "type": "tool_call"}])
+
+
+def test_tool_result_is_withheld_and_navigable():
+    app, session = _graph([bureau_report])
+    out = app.invoke({"messages": [_call("bureau_report", {"applicant": 99}, "c1")]})
+    tm = out["messages"][-1]
+
+    assert tm.content.startswith('[halo] map "99"')
+    assert tm.artifact["halo"] == "1"
+    # the model never sees the payload; the session fetches it back, verified
+    got = session.fetch(["99.profile"])["99.profile"]
+    assert got == {"ok": True, "value": {"debts": {"monthly": 2604}, "income": {"monthly": 4200}}}
+
+
+def test_nav_tool_runs_in_graph_and_is_not_re_encoded():
+    app, session = _graph([bureau_report])
+    app.invoke({"messages": [_call("bureau_report", {"applicant": 99}, "c1")]})
+    out = app.invoke({"messages": [_call("halo_fetch", {"refs": ["99.profile"]}, "c2")]})
+    ftm = out["messages"][-1]
+    assert not ftm.content.startswith("[halo] map")  # passed through, not turned into a map
+    assert "income" in ftm.content
+
+
+def test_entity_accumulation_folds_two_calls_into_one_map():
+    # threshold low enough that the (modest) appointments result also crosses it and is ingested.
+    app, session = _graph([bureau_report, get_appointments], threshold=256)
+    app.invoke({"messages": [_call("bureau_report", {"applicant": 123}, "c1")]})
+    out = app.invoke({"messages": [_call("get_appointments", {"applicant": 123}, "c2")]})
+    tm = out["messages"][-1]
+
+    # second call for the same id folds in: the map is now namespaced by tool name
+    assert tm.artifact["source"]["id"] == "123"
+    branches = set(tm.artifact["view"]["branches"])
+    assert {"bureau_report", "get_appointments"} <= branches

halo_format_langgraph-0.2.0/tests/test_install.py

@@ -0,0 +1,50 @@
+"""install_halo (the create_agent path) and halo_tool_node (the StateGraph path): both append the
+navigation tool and wire the wrapper non-destructively, and both share one session."""
+
+from langchain_core.tools import tool
+
+from halo_format_langgraph import (
+    HaloMiddleware,
+    HaloSession,
+    halo_tool_node,
+    install_halo,
+)
+from halo_format_langgraph.constants import HALO_FETCH_TOOL
+
+
+@tool
+def existing(x: int) -> dict:
+    """An existing tool."""
+    return {"x": x}
+
+
+def test_install_halo_appends_tool_and_middleware_preserving_existing():
+    class OtherMW:  # a stand-in for the host's own middleware
+        pass
+
+    other = OtherMW()
+    result = install_halo(tools=[existing], middleware=[other])
+
+    assert [t.name for t in result.tools] == ["existing", HALO_FETCH_TOOL]
+    assert result.middleware[0] is other
+    assert isinstance(result.middleware[-1], HaloMiddleware)
+    assert isinstance(result.session, HaloSession)
+
+
+def test_install_halo_with_no_inputs():
+    result = install_halo()
+    assert [t.name for t in result.tools] == [HALO_FETCH_TOOL]
+    assert len(result.middleware) == 1
+
+
+def test_install_halo_shares_passed_session():
+    session = HaloSession()
+    result = install_halo(tools=[existing], session=session)
+    assert result.session is session
+
+
+def test_halo_tool_node_builds_node_with_appended_tool():
+    result = halo_tool_node([existing])
+    assert [t.name for t in result.tools] == ["existing", HALO_FETCH_TOOL]
+    assert isinstance(result.session, HaloSession)
+    assert result.tool_node is not None

halo_format_langgraph-0.2.0/tests/test_middleware.py

@@ -0,0 +1,101 @@
+"""The encode middleware: the wrapper rewrites a large ToolMessage into a shape map (content) plus the
+envelope (artifact), and passes through everything it must — the nav tool, small results, and non-
+ToolMessage returns (a Command). Sync and async share one body, so both are exercised."""
+
+import asyncio
+from types import SimpleNamespace
+
+from langchain_core.messages import ToolMessage
+from langgraph.types import Command
+
+from halo_format_langgraph import HaloMiddleware, HaloSession
+from halo_format_langgraph.middleware import _PRIOR_ARTIFACT_KEY
+
+BIG = '{"profile":{"income":{"monthly":4200},"debts":{"monthly":2604}},"filler":"' + "x" * 3000 + '"}'
+
+
+def _req(name, args):
+    # The wrapper only reads request.tool_call; a namespace is enough for the unit level.
+    return SimpleNamespace(tool_call={"name": name, "args": args, "id": "c1"})
+
+
+def _handler(content, artifact=None):
+    def handler(request):
+        return ToolMessage(
+            content=content, tool_call_id="c1", name=request.tool_call["name"], artifact=artifact
+        )
+
+    return handler
+
+
+def _mw():
+    session = HaloSession(now=lambda: "T")
+    return HaloMiddleware(session, threshold=2048), session
+
+
+def test_large_result_becomes_shape_map_with_envelope_artifact():
+    mw, session = _mw()
+    out = mw.wrap_tool_call(_req("bureau", {"applicant": 99}), _handler(BIG))
+
+    assert out.content.startswith('[halo] map "99"')  # arg_join keyed on applicant=99
+    assert out.artifact["halo"] == "1"
+    assert out.artifact["source"]["id"] == "99"
+    # the full payload is reachable from the store, not in content
+    assert session.fetch(["99.profile"])["99.profile"]["ok"] is True
+
+
+def test_async_path_matches_sync():
+    session = HaloSession(now=lambda: "T")
+    mw = HaloMiddleware(session, 2048)
+
+    async def handler(request):
+        return ToolMessage(content=BIG, tool_call_id="c1", name=request.tool_call["name"])
+
+    out = asyncio.run(mw.awrap_tool_call(_req("bureau", {"applicant": 99}), handler))
+    assert out.content.startswith('[halo] map "99"')
+    assert out.artifact["halo"] == "1"
+
+
+def test_nav_tool_output_passes_through_untouched():
+    # MANDATORY: a fetched leaf must never be re-encoded into a new map.
+    mw, _ = _mw()
+    out = mw.wrap_tool_call(_req("halo_fetch", {"refs": ["x"]}), _handler(BIG))
+    assert out.content == BIG
+    assert out.artifact is None
+
+
+def test_small_result_passes_through():
+    mw, _ = _mw()
+    out = mw.wrap_tool_call(_req("ping", {"x": 1}), _handler('{"ok":true}'))
+    assert out.content == '{"ok":true}'
+    assert out.artifact is None
+
+
+def test_command_return_passes_through():
+    mw, _ = _mw()
+
+    def handler(request):
+        return Command(update={"foo": "bar"})
+
+    out = mw.wrap_tool_call(_req("set_state", {"a": 1}), handler)
+    assert isinstance(out, Command)
+
+
+def test_upstream_artifact_is_preserved():
+    mw, _ = _mw()
+    out = mw.wrap_tool_call(_req("with_art", {"a": 7}), _handler(BIG, artifact={"mine": 1}))
+    assert out.artifact["halo"] == "1"  # Halo's envelope takes the artifact slot
+    assert out.additional_kwargs[_PRIOR_ARTIFACT_KEY] == {"mine": 1}  # upstream artifact kept
+
+
+def test_original_message_not_mutated():
+    # _rewrite returns a copy; the handler's message object is left intact.
+    mw, _ = _mw()
+    original = ToolMessage(content=BIG, tool_call_id="c1", name="bureau")
+
+    def handler(request):
+        return original
+
+    out = mw.wrap_tool_call(_req("bureau", {"applicant": 99}), handler)
+    assert out is not original
+    assert original.content == BIG  # untouched

halo_format_langgraph-0.2.0/tests/test_nav_tool.py

@@ -0,0 +1,66 @@
+"""The navigation tool: a single LangChain tool, halo_fetch, declared content_and_artifact. A leaf ref
+returns its value; a branch ref returns its sub-shape rather than erroring; the per-ref result rides in
+both content (read by the model) and artifact (kept in state)."""
+
+import json
+
+from halo_format_langgraph import HaloSession, create_halo_fetch_tool
+from halo_format_langgraph.constants import HALO_FETCH_TOOL
+from halo_format_langgraph.nav_tool import halo_fetch
+
+
+def _seed():
+    # Large enough (> the core's 1024-byte inline threshold) that the top-level object carves into
+    # branches: a scalar leaf (score) and a chunked-array branch (tradelines).
+    session = HaloSession(now=lambda: "T")
+    session.ingest(
+        "bureau",
+        {"applicant": 99},
+        {
+            "score": 612,
+            "tradelines": [
+                {"id": i, "creditor": f"Bank {i}", "balance": i * 137, "status": "open"}
+                for i in range(40)
+            ],
+        },
+    )
+    return session
+
+
+def test_helper_fetches_leaf_verified():
+    session = _seed()
+    got = halo_fetch(session, ["99.score"])
+    assert got["99.score"] == {"ok": True, "value": 612}
+
+
+def test_helper_branch_ref_returns_sub_shape():
+    session = _seed()
+    got = halo_fetch(session, ["99.tradelines"])
+    assert got["99.tradelines"]["ok"] is True
+    assert got["99.tradelines"]["kind"] == "branch"
+    assert any(f["ref"] == "99.tradelines.0" for f in got["99.tradelines"]["fields"])
+
+
+def test_tool_is_named_and_content_and_artifact():
+    session = _seed()
+    tool = create_halo_fetch_tool(session)
+    assert tool.name == HALO_FETCH_TOOL
+    assert tool.response_format == "content_and_artifact"
+
+
+def test_tool_invocation_returns_content_and_artifact():
+    session = _seed()
+    tool = create_halo_fetch_tool(session)
+    msg = tool.invoke(
+        {"type": "tool_call", "name": HALO_FETCH_TOOL, "args": {"refs": ["99.score"]}, "id": "c1"}
+    )
+    # content is the JSON the model reads; artifact is the same structured result kept in state.
+    assert json.loads(msg.content)["99.score"] == {"ok": True, "value": 612}
+    assert msg.artifact["99.score"] == {"ok": True, "value": 612}
+
+
+def test_bad_ref_is_per_entry_error_not_a_raise():
+    session = _seed()
+    got = halo_fetch(session, ["99.score", "99.missing"])
+    assert got["99.score"]["ok"] is True
+    assert got["99.missing"]["ok"] is False