trytilde-langchain 3.0.1__tar.gz

trytilde_langchain-3.0.1/.gitignore

@@ -0,0 +1,51 @@
+/target/
+/dist/
+node_modules/
+# Build output of an older example-agent layout; the examples live under sdk/ts/examples.
+/dev/example-agent-1/
+/web/dist/
+/.tools/
+/.env.*
+!/.env.example
+!/.env.test
+/.run/
+.run/
+
+/sdk/ts/**/dist/
+# Generated TypeScript contracts; @trytilde/contracts builds them from proto/.
+/sdk/ts/packages/contracts/gen/
+
+/web/provider-dist/
+
+__pycache__/
+
+# Local runtime credentials must not enter the initial repository commit.
+/.env
+log
+
+/.local/
+
+# Bifrost benchmark container state
+/dev/inference-bench/bifrost/*
+!/dev/inference-bench/bifrost/config.json
+
+# Local Claude Code worktrees
+/.claude/worktrees/
+
+# Python SDK: uv environments and generated contracts (sdk/py/scripts/generate.py).
+/sdk/py/.venv/
+/sdk/py/.venv-crewai/
+/sdk/py/**/.venv/
+/sdk/py/packages/tilde/src/tilde/agent_event_ingress/
+/sdk/py/packages/tilde/src/tilde/agent_host/
+/sdk/py/packages/tilde/src/tilde/ingress/
+/sdk/py/packages/tilde/src/tilde/management/
+/sdk/py/packages/tilde/src/tilde/provider/
+/sdk/py/packages/tilde/src/tilde/run/
+/sdk/py/packages/tilde/src/tilde/runtime/
+/sdk/py/packages/tilde/src/tilde/setup/
+/sdk/py/packages/tilde/src/tilde/tool_host/
+/sdk/py/packages/tilde/src/tilde/types/
+/sdk/py/**/*.egg-info/
+.pytest_cache/
+.ruff_cache/

trytilde_langchain-3.0.1/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.5
+Name: trytilde-langchain
+Version: 3.0.1
+Summary: Tilde adapter for LangChain and LangGraph: typed context to LangChain messages and channel tools
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: langchain-core<2,>=1
+Requires-Dist: langchain<2,>=1
+Requires-Dist: langgraph<2,>=1
+Requires-Dist: trytilde
+Description-Content-Type: text/markdown
+
+# LangChain / LangGraph adapter
+
+Core history and delivery live in `trytilde`. This package converts typed
+context to LangChain messages and channel tools to LangChain tools, brings each
+invocation to a module-level `create_agent` graph through `tilde_middleware()`,
+and lets `tilde deploy` discover the agent's prompts.
+
+```python
+import tilde
+from langchain.agents import create_agent
+from langchain_openai import ChatOpenAI
+from tilde_langchain import convert_to_langchain_messages, tilde_middleware
+
+INFERENCE = tilde.inference("default")
+agent = create_agent(
+    ChatOpenAI(
+        model="gpt-4o-mini",
+        base_url=INFERENCE.base_url,
+        api_key=INFERENCE.api_key,
+        http_async_client=INFERENCE.async_client(),
+    ),
+    system_prompt="Respond using the current channel's tools. Returned model text is private.",
+    middleware=[tilde_middleware()],
+)
+
+
+async def run(ctx):
+    history = await ctx.message.history()
+    messages = await convert_to_langchain_messages(history.items, context=ctx)
+    await agent.ainvoke({"messages": messages}, {"recursion_limit": 16})
+```
+
+A compiled graph takes no per-call tools or messages (`ainvoke`'s config carries
+callbacks and `context`, and callbacks cannot change state), so the invocation's
+pieces come from middleware the graph is created with once. `tilde_middleware()`
+reads the running invocation from Tilde's context variable and does nothing
+outside one:
+
+- before each model call it checks cancellation and adds steering input as user
+  messages to the graph state, so later calls keep them;
+- around each model call it adds the current channel's tools and, when skills are
+  assigned (plain `create_agent` has no native skills), the `list_skills` /
+  `read_skill` tools plus `ctx.skills.summary()` as a second system message;
+  it also stamps the invocation's inference calls with every `@dynamic_prompt`
+  listed after it, so put it first;
+- around tool calls it executes those tools. They are not registered with the
+  graph's `ToolNode`; `create_agent` allows that when middleware executes them
+  in `wrap_tool_call`.
+
+The hooks are async only; use `ainvoke` / `astream`.
+
+## Deploy discovery
+
+`tilde deploy` (entry point `tilde.discover`) registers:
+
+- a module-level `create_agent` graph's static `system_prompt` as the plain prompt
+  `<name>/system_prompt` (`create_agent(name=...)`, else the variable name), read
+  from the model node's closure (langchain 1.4; a warning when unreadable), and every
+  `@dynamic_prompt` middleware in the graph;
+- a `@dynamic_prompt` middleware as the dynamic prompt `<function>/system_prompt`
+  with the function's source;
+- module-level `PromptTemplate`s as `<variable>` and `ChatPromptTemplate` messages as
+  `<variable>/<index>.<role>`: f-string templates in braces format, mustache in
+  mustache format. Jinja2 templates and LangSmith hub prompts are reported, not
+  registered.
+
+History pages are chronological; pass `before_message_id=history.next_page_token`
+for older messages. The latest page includes the current objective unless it
+already matches the latest received message. `include_objective=False` omits it.
+`include_work=True` also reads current goals/tasks and requires `work.read`.
+Only the acting agent's messages become `AIMessage`; everything else is a
+`HumanMessage`. Every converted message carries the Tilde message id.
+
+Images and PDFs are downloaded through `ctx.attachments.download` and embedded as
+standard `image` / `file` content blocks (base64 with `mime_type`). Text files
+include their real content. Unsupported binary formats get an explicit
+attachment description; use `on_attachment` to parse them yourself. No private
+URL or credential needs to be exposed to the model.
+
+```python
+from langchain_core.messages import HumanMessage
+from tilde_langchain import MessageHandlers
+
+history = await ctx.message.history(include_work=True)
+messages = await convert_to_langchain_messages(
+    history.items,
+    context=ctx,
+    on_message=MessageHandlers(
+        goal=lambda item: HumanMessage(id=item.id, content=f"Our goal: {item.goal.objective}"),
+        task=lambda item: None,  # Omit this type, or provide a different rendering.
+    ),
+    on_attachment=decode_attachment,  # async def decode_attachment(conversion) -> block | None
+)
+```
+
+`MessageHandlers` supports `message`, `objective`, `goal` and `task`; each may
+be sync or async. Supplied handlers take precedence over cached/default
+rendering; returning `None` omits an item. Without an override the converter
+renders all supported types and skips conversation messages whose status is
+not `complete`. Completed, attachment-free conversions use the existing
+per-agent cache in bounded batches (100 items or 1 MiB) as plain
+`{"id", "role", "content"}` JSON. Files are hydrated afresh and are never
+stored in the cache; objectives/goals/tasks remain live projections rather
+than cached chat records. A cached representation is only reused when its id
+and role match and it contains no `image`/`file` block.
+
+## Channel tools
+
+`tilde_middleware()` converts the channel's tools itself; convert them yourself for
+graphs built per invocation or `create_react_agent`. Tools are async only and run on
+the agent's event loop, so cancelling the invocation cancels in-flight channel calls.
+
+`convert_to_langchain_tools(ctx.channel.current)` preserves the provider's
+descriptions and JSON schemas (passed to LangChain as a JSON-schema
+`args_schema`) and forwards the model's tool-call id to Tilde's audited tool
+execution. It does not publish the model's final text. The agent chooses the
+provider tool and arguments, including routing fields required by that provider.
+
+The tool-call id comes from the `ToolCall` dict LangGraph's `ToolNode` (and so
+`create_agent`) passes to `tool.ainvoke`. Invoking a tool directly with plain
+arguments has no call id; a random UUID is generated so the call is still
+audited, but repeated executions are not deduplicated in that case.
+
+Override tool instructions with `instructions={"sendMessage": "..."}`, or change
+the channel tool's `description` before conversion. When combining namespaces,
+use `prefix="slack_"` (or another prefix) to keep model tool names distinct.
+Names are sanitized to `[a-zA-Z0-9_-]`, and names over 64 characters are truncated with a
+stable hash suffix; collisions raise.
+
+The core SDK exposes typed callable tools on `ctx.channel.slack`, `github`,
+`agentmail`, `linq`, `whatsapp`, `telnyx_whatsapp` and `native`, plus
+`ctx.channel.connections()` / `ctx.channel.for_connection(id)` when several
+connections use one provider. `ctx.channel.current` never falls back to a
+different connection when the inbound connection has no available tools.
+
+## Bundled tools
+
+The agent's own LangChain tools join Tilde's with one call:
+
+```python
+from langchain_core.tools import tool
+from tilde import BundledOptions
+from tilde_langchain import with_tilde_tools
+
+
+@tool
+def roll_dice(count: int = 1) -> list[int]:
+    """Roll six-sided dice."""
+    return [random.randint(1, 6) for _ in range(count)]
+
+
+roll_dice.metadata = {"tilde": BundledOptions(summary="Rolled dice")}
+agent = create_agent(model, tools=await with_tilde_tools(ctx, [roll_dice]))
+```
+
+`with_tilde_tools` returns the current channel's tools, `ctx.agent_tools` and copies of the
+native tools, and publishes the native tools to Tilde with the argument schema the model sees,
+so `tools.search` finds them and a `tools.execute` naming one runs it here. Each copy keeps its
+type and gets an audit callback handler, so `ToolNode` injection keeps working and every call
+is audited once with the model's call id. `options={"roll_dice": BundledOptions(...)}` overrides
+`metadata["tilde"]`. LangChain has no output schema and audits record the tool message content;
+a `ToolException` handled for the model is audited as failed. Tools that need `ToolRuntime` or
+`InjectedState` only get them from `ToolNode`, so they cannot run through `tools.execute`.

trytilde_langchain-3.0.1/README.md

@@ -0,0 +1,163 @@
+# LangChain / LangGraph adapter
+
+Core history and delivery live in `trytilde`. This package converts typed
+context to LangChain messages and channel tools to LangChain tools, brings each
+invocation to a module-level `create_agent` graph through `tilde_middleware()`,
+and lets `tilde deploy` discover the agent's prompts.
+
+```python
+import tilde
+from langchain.agents import create_agent
+from langchain_openai import ChatOpenAI
+from tilde_langchain import convert_to_langchain_messages, tilde_middleware
+
+INFERENCE = tilde.inference("default")
+agent = create_agent(
+    ChatOpenAI(
+        model="gpt-4o-mini",
+        base_url=INFERENCE.base_url,
+        api_key=INFERENCE.api_key,
+        http_async_client=INFERENCE.async_client(),
+    ),
+    system_prompt="Respond using the current channel's tools. Returned model text is private.",
+    middleware=[tilde_middleware()],
+)
+
+
+async def run(ctx):
+    history = await ctx.message.history()
+    messages = await convert_to_langchain_messages(history.items, context=ctx)
+    await agent.ainvoke({"messages": messages}, {"recursion_limit": 16})
+```
+
+A compiled graph takes no per-call tools or messages (`ainvoke`'s config carries
+callbacks and `context`, and callbacks cannot change state), so the invocation's
+pieces come from middleware the graph is created with once. `tilde_middleware()`
+reads the running invocation from Tilde's context variable and does nothing
+outside one:
+
+- before each model call it checks cancellation and adds steering input as user
+  messages to the graph state, so later calls keep them;
+- around each model call it adds the current channel's tools and, when skills are
+  assigned (plain `create_agent` has no native skills), the `list_skills` /
+  `read_skill` tools plus `ctx.skills.summary()` as a second system message;
+  it also stamps the invocation's inference calls with every `@dynamic_prompt`
+  listed after it, so put it first;
+- around tool calls it executes those tools. They are not registered with the
+  graph's `ToolNode`; `create_agent` allows that when middleware executes them
+  in `wrap_tool_call`.
+
+The hooks are async only; use `ainvoke` / `astream`.
+
+## Deploy discovery
+
+`tilde deploy` (entry point `tilde.discover`) registers:
+
+- a module-level `create_agent` graph's static `system_prompt` as the plain prompt
+  `<name>/system_prompt` (`create_agent(name=...)`, else the variable name), read
+  from the model node's closure (langchain 1.4; a warning when unreadable), and every
+  `@dynamic_prompt` middleware in the graph;
+- a `@dynamic_prompt` middleware as the dynamic prompt `<function>/system_prompt`
+  with the function's source;
+- module-level `PromptTemplate`s as `<variable>` and `ChatPromptTemplate` messages as
+  `<variable>/<index>.<role>`: f-string templates in braces format, mustache in
+  mustache format. Jinja2 templates and LangSmith hub prompts are reported, not
+  registered.
+
+History pages are chronological; pass `before_message_id=history.next_page_token`
+for older messages. The latest page includes the current objective unless it
+already matches the latest received message. `include_objective=False` omits it.
+`include_work=True` also reads current goals/tasks and requires `work.read`.
+Only the acting agent's messages become `AIMessage`; everything else is a
+`HumanMessage`. Every converted message carries the Tilde message id.
+
+Images and PDFs are downloaded through `ctx.attachments.download` and embedded as
+standard `image` / `file` content blocks (base64 with `mime_type`). Text files
+include their real content. Unsupported binary formats get an explicit
+attachment description; use `on_attachment` to parse them yourself. No private
+URL or credential needs to be exposed to the model.
+
+```python
+from langchain_core.messages import HumanMessage
+from tilde_langchain import MessageHandlers
+
+history = await ctx.message.history(include_work=True)
+messages = await convert_to_langchain_messages(
+    history.items,
+    context=ctx,
+    on_message=MessageHandlers(
+        goal=lambda item: HumanMessage(id=item.id, content=f"Our goal: {item.goal.objective}"),
+        task=lambda item: None,  # Omit this type, or provide a different rendering.
+    ),
+    on_attachment=decode_attachment,  # async def decode_attachment(conversion) -> block | None
+)
+```
+
+`MessageHandlers` supports `message`, `objective`, `goal` and `task`; each may
+be sync or async. Supplied handlers take precedence over cached/default
+rendering; returning `None` omits an item. Without an override the converter
+renders all supported types and skips conversation messages whose status is
+not `complete`. Completed, attachment-free conversions use the existing
+per-agent cache in bounded batches (100 items or 1 MiB) as plain
+`{"id", "role", "content"}` JSON. Files are hydrated afresh and are never
+stored in the cache; objectives/goals/tasks remain live projections rather
+than cached chat records. A cached representation is only reused when its id
+and role match and it contains no `image`/`file` block.
+
+## Channel tools
+
+`tilde_middleware()` converts the channel's tools itself; convert them yourself for
+graphs built per invocation or `create_react_agent`. Tools are async only and run on
+the agent's event loop, so cancelling the invocation cancels in-flight channel calls.
+
+`convert_to_langchain_tools(ctx.channel.current)` preserves the provider's
+descriptions and JSON schemas (passed to LangChain as a JSON-schema
+`args_schema`) and forwards the model's tool-call id to Tilde's audited tool
+execution. It does not publish the model's final text. The agent chooses the
+provider tool and arguments, including routing fields required by that provider.
+
+The tool-call id comes from the `ToolCall` dict LangGraph's `ToolNode` (and so
+`create_agent`) passes to `tool.ainvoke`. Invoking a tool directly with plain
+arguments has no call id; a random UUID is generated so the call is still
+audited, but repeated executions are not deduplicated in that case.
+
+Override tool instructions with `instructions={"sendMessage": "..."}`, or change
+the channel tool's `description` before conversion. When combining namespaces,
+use `prefix="slack_"` (or another prefix) to keep model tool names distinct.
+Names are sanitized to `[a-zA-Z0-9_-]`, and names over 64 characters are truncated with a
+stable hash suffix; collisions raise.
+
+The core SDK exposes typed callable tools on `ctx.channel.slack`, `github`,
+`agentmail`, `linq`, `whatsapp`, `telnyx_whatsapp` and `native`, plus
+`ctx.channel.connections()` / `ctx.channel.for_connection(id)` when several
+connections use one provider. `ctx.channel.current` never falls back to a
+different connection when the inbound connection has no available tools.
+
+## Bundled tools
+
+The agent's own LangChain tools join Tilde's with one call:
+
+```python
+from langchain_core.tools import tool
+from tilde import BundledOptions
+from tilde_langchain import with_tilde_tools
+
+
+@tool
+def roll_dice(count: int = 1) -> list[int]:
+    """Roll six-sided dice."""
+    return [random.randint(1, 6) for _ in range(count)]
+
+
+roll_dice.metadata = {"tilde": BundledOptions(summary="Rolled dice")}
+agent = create_agent(model, tools=await with_tilde_tools(ctx, [roll_dice]))
+```
+
+`with_tilde_tools` returns the current channel's tools, `ctx.agent_tools` and copies of the
+native tools, and publishes the native tools to Tilde with the argument schema the model sees,
+so `tools.search` finds them and a `tools.execute` naming one runs it here. Each copy keeps its
+type and gets an audit callback handler, so `ToolNode` injection keeps working and every call
+is audited once with the model's call id. `options={"roll_dice": BundledOptions(...)}` overrides
+`metadata["tilde"]`. LangChain has no output schema and audits record the tool message content;
+a `ToolException` handled for the model is audited as failed. Tools that need `ToolRuntime` or
+`InjectedState` only get them from `ToolNode`, so they cannot run through `tools.execute`.

trytilde_langchain-3.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "trytilde-langchain"
+version = "3.0.1"
+description = "Tilde adapter for LangChain and LangGraph: typed context to LangChain messages and channel tools"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+dependencies = ["trytilde", "langchain-core>=1,<2", "langchain>=1,<2", "langgraph>=1,<2"]
+
+# `tilde deploy` reads create_agent graphs, dynamic prompts and prompt templates through this.
+[project.entry-points."tilde.discover"]
+langchain = "tilde_langchain.discover:discover"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tilde_langchain"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/tilde_langchain", "README.md"]

trytilde_langchain-3.0.1/src/tilde_langchain/__init__.py

@@ -0,0 +1,33 @@
+"""Tilde adapter for LangChain / LangGraph.
+
+Core history and delivery live in ``tilde``; this package converts typed context to LangChain
+messages, exposes channel tools as LangChain ``BaseTool`` instances, brings the invocation to a
+module-level ``create_agent`` graph through ``tilde_middleware()`` and lets ``tilde deploy``
+discover its prompts.
+"""
+
+from tilde_langchain.attachments import (
+    AttachmentConversion,
+    AttachmentHandler,
+    ContentBlock,
+    convert_attachment,
+)
+from tilde_langchain.discover import discover
+from tilde_langchain.messages import MessageHandlers, convert_to_langchain_messages
+from tilde_langchain.middleware import TildeMiddleware, tilde_middleware
+from tilde_langchain.tools import ChannelToolAdapter, convert_to_langchain_tools, with_tilde_tools
+
+__all__ = [
+    "AttachmentConversion",
+    "AttachmentHandler",
+    "ChannelToolAdapter",
+    "ContentBlock",
+    "MessageHandlers",
+    "TildeMiddleware",
+    "convert_attachment",
+    "convert_to_langchain_messages",
+    "convert_to_langchain_tools",
+    "discover",
+    "tilde_middleware",
+    "with_tilde_tools",
+]

trytilde_langchain-3.0.1/src/tilde_langchain/attachments.py

@@ -0,0 +1,83 @@
+"""Attachment hydration into LangChain standard content blocks (langchain-core 1.x)."""
+
+from __future__ import annotations
+
+import base64
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from tilde import ConversationMessage, DownloadedAttachment
+from tilde.types.v1.chat_pb2 import Attachment
+
+ContentBlock = dict[str, Any]
+"""A ``langchain_core.messages.content`` block: ``{"type": "text", ...}``, ``image``, ``file``."""
+
+_TEXT_TYPES = {"application/json", "application/xml"}
+_FILE_TYPES = {"image/jpeg", "image/png", "image/gif", "image/webp", "application/pdf"}
+_EXTENSIONS = {
+    "jpg": "image/jpeg",
+    "jpeg": "image/jpeg",
+    "png": "image/png",
+    "gif": "image/gif",
+    "webp": "image/webp",
+    "pdf": "application/pdf",
+    "txt": "text/plain",
+    "md": "text/plain",
+    "csv": "text/plain",
+    "log": "text/plain",
+    "json": "application/json",
+    "xml": "application/xml",
+}
+
+
+@dataclass(slots=True)
+class AttachmentConversion:
+    message: ConversationMessage
+    attachment: Attachment
+    download: Callable[[], Awaitable[DownloadedAttachment]]
+    """Uses the current invocation's authenticated, thread-scoped attachment API."""
+
+
+AttachmentResult = ContentBlock | list[ContentBlock] | None
+AttachmentHandler = Callable[[AttachmentConversion], AttachmentResult | Awaitable[AttachmentResult]]
+
+
+async def convert_attachment(input: AttachmentConversion) -> AttachmentResult:
+    """Hydrate images/PDFs as base64 blocks and textual files as actual text, not filenames."""
+    attachment = input.attachment
+    media_type = normalize_media_type(attachment.media_type, attachment.filename)
+    text = media_type.startswith("text/") or media_type in _TEXT_TYPES
+    file = media_type in _FILE_TYPES
+    if not text and not file:
+        return {
+            "type": "text",
+            "text": (
+                f"Attached file: {attachment.filename} ({media_type}). "
+                "A custom attachment handler is needed to read this format."
+            ),
+        }
+    result = await input.download()
+    if result.attachment.id != attachment.id:
+        raise RuntimeError("Attachment download returned a different file")
+    if text:
+        content = result.content.decode("utf-8", errors="replace")
+        return {"type": "text", "text": f"Attached file: {attachment.filename}\n{content}"}
+    encoded = base64.b64encode(result.content).decode("ascii")
+    if media_type.startswith("image/"):
+        return {"type": "image", "mime_type": media_type, "base64": encoded}
+    # ``filename`` is not part of FileContentBlock but the OpenAI translator forwards it.
+    return {
+        "type": "file",
+        "mime_type": media_type,
+        "base64": encoded,
+        "filename": attachment.filename,
+    }
+
+
+def normalize_media_type(value: str, filename: str) -> str:
+    media_type = value.split(";")[0].strip().lower()
+    if media_type and media_type != "application/octet-stream":
+        return media_type
+    extension = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
+    return _EXTENSIONS.get(extension, media_type or "application/octet-stream")

trytilde_langchain-3.0.1/src/tilde_langchain/discover.py

@@ -0,0 +1,253 @@
+"""``tilde deploy`` discovery for LangChain (entry point ``tilde.discover``).
+
+- A module-level ``create_agent`` graph: its static ``system_prompt`` becomes the plain prompt
+  ``<agent>/system_prompt`` (``<agent>`` is the ``name=`` given to ``create_agent``, else the
+  variable name), and every ``@dynamic_prompt`` middleware in it a dynamic prompt.
+- A module-level ``@dynamic_prompt`` middleware: ``<function name>/system_prompt``, dynamic,
+  with the function's source.
+- A module-level ``PromptTemplate`` / ``ChatPromptTemplate``: ``<variable>`` (chat templates:
+  ``<variable>/<index>.<role>`` per message), f-string templates in braces format, mustache in
+  mustache format. Jinja2 templates and LangSmith hub prompts are reported, not registered.
+
+Tools are declared as ``with_tilde_tools`` publishes them: those of a ``create_agent`` graph's
+``ToolNode`` (``tools=`` and middleware tools) and a ``define_tools`` value of LangChain tools.
+
+``create_agent`` keeps the system prompt and ``wrap_model_call`` middleware only in the model
+node's closures (langchain 1.4); they are read from there and reported when unreadable.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import sys
+import types
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from langchain.agents.middleware import AgentMiddleware
+from langchain_core.messages import BaseMessage
+from langchain_core.prompts import (
+    ChatPromptTemplate,
+    MessagesPlaceholder,
+    PromptTemplate,
+)
+from langchain_core.tools import BaseTool
+from langgraph.graph.state import CompiledStateGraph
+from langgraph.prebuilt import ToolNode
+
+from tilde import BundledTools
+from tilde.discovery import (
+    PROMPT_FORMAT_BRACES,
+    PROMPT_FORMAT_DYNAMIC,
+    PROMPT_FORMAT_MUSTACHE,
+    PROMPT_FORMAT_PLAIN,
+    Discovered,
+    DiscoveryContext,
+    declared_prompt,
+    declared_tool,
+)
+from tilde.prompts import canonical_json, prompt_hash, valid_prompt_name
+from tilde_langchain.tools import describe_tool
+
+_FORMATS = {"f-string": PROMPT_FORMAT_BRACES, "mustache": PROMPT_FORMAT_MUSTACHE}
+_DEFAULT_GRAPH_NAME = "LangGraph"
+
+
+def is_create_agent(value: Any) -> bool:
+    return isinstance(value, CompiledStateGraph) and (
+        (value.config or {}).get("metadata", {}).get("ls_integration") == "langchain_create_agent"
+    )
+
+
+def reachable_middleware(root: Any) -> list[AgentMiddleware[Any, Any]]:
+    """Middleware instances reachable from ``root`` through bound methods, wrappers, partials
+    and closures: from a ``create_agent`` model node, or from a ``wrap_model_call`` handler."""
+    found: list[AgentMiddleware[Any, Any]] = []
+    seen: set[int] = set()
+    pending = [root]
+    while pending:
+        value = pending.pop()
+        if id(value) in seen:
+            continue
+        seen.add(id(value))
+        if isinstance(value, AgentMiddleware):
+            found.append(value)
+        elif inspect.ismethod(value):
+            pending += [value.__self__, value.__func__]
+        elif isinstance(value, functools.partial):
+            pending += [value.func, *value.args]
+        elif isinstance(value, types.FunctionType):
+            for cell in value.__closure__ or ():
+                try:
+                    pending.append(cell.cell_contents)
+                except ValueError:  # an empty cell
+                    continue
+        elif isinstance(value, list | tuple):
+            pending += list(value)
+        wrapped = getattr(value, "__wrapped__", None)
+        if wrapped is not None:
+            pending.append(wrapped)
+    return found
+
+
+def dynamic_prompt_function(middleware: AgentMiddleware[Any, Any]) -> Callable[..., Any] | None:
+    """The function behind a ``@dynamic_prompt`` middleware (the class ``dynamic_prompt``
+    builds keeps it in its hook's closure)."""
+    for hook in ("wrap_model_call", "awrap_model_call"):
+        method = type(middleware).__dict__.get(hook)
+        if not isinstance(method, types.FunctionType):
+            continue
+        if not method.__qualname__.startswith("dynamic_prompt."):
+            return None
+        for name, cell in zip(method.__code__.co_freevars, method.__closure__ or (), strict=True):
+            if name == "func":
+                return cell.cell_contents
+    return None
+
+
+def dynamic_prompt(middleware: AgentMiddleware[Any, Any]) -> tuple[str, str] | None:
+    """``(name, source)`` of a ``@dynamic_prompt`` middleware, or None for other middleware."""
+    func = dynamic_prompt_function(middleware)
+    if func is None:
+        return None
+    try:
+        return f"{middleware.name}/system_prompt", inspect.getsource(func)
+    except (OSError, TypeError):
+        return None
+
+
+def dynamic_stamp(middleware: AgentMiddleware[Any, Any]) -> tuple[str, str] | None:
+    prompt = dynamic_prompt(middleware)
+    if prompt is None:
+        return None
+    return prompt[0], prompt_hash(prompt[1], {}, canonical_json({}))
+
+
+def discover(value: Any, context: DiscoveryContext) -> Discovered | None:
+    module = sys.modules.get(context.module)
+    file = getattr(module, "__file__", None)
+    origin = f"{context.relative(Path(file)) if file else context.module}#{context.name}"
+    if isinstance(value, BundledTools):
+        if not value.tools or not all(isinstance(tool, BaseTool) for tool in value.tools):
+            return None
+        return Discovered(
+            tools=[
+                declared_tool(describe_tool(tool, value.options), f"{origin}.tools.{tool.name}")
+                for tool in value.tools
+            ]
+        )
+    if is_create_agent(value):
+        return _agent(value, origin, context)
+    if isinstance(value, AgentMiddleware):
+        found = Discovered()
+        _dynamic(value, origin, found, context)
+        return found
+    if isinstance(value, PromptTemplate | ChatPromptTemplate):
+        if (value.metadata or {}).get("lc_hub_repo"):
+            context.warn(f"{origin}: LangSmith hub prompt is versioned by the hub, not by Tilde")
+            return None
+        found = Discovered()
+        if isinstance(value, PromptTemplate):
+            _template(context.name, value, origin, found, context)
+        elif isinstance(value, ChatPromptTemplate):
+            _chat(value, origin, found, context)
+        return found
+    return None
+
+
+def _agent(graph: CompiledStateGraph, origin: str, context: DiscoveryContext) -> Discovered:
+    found = Discovered()
+    name = graph.name if graph.name != _DEFAULT_GRAPH_NAME else context.name
+    model = graph.nodes.get("model")
+    bound = getattr(model, "bound", None)
+    func = getattr(bound, "func", None)
+    try:
+        nonlocals = inspect.getclosurevars(func).nonlocals
+        system = nonlocals["system_message"]
+    except (KeyError, TypeError):
+        context.warn(f"{origin}: create_agent's system prompt could not be read")
+        system = None
+    if isinstance(system, BaseMessage):
+        if isinstance(system.content, str) and valid_prompt_name(f"{name}/system_prompt"):
+            found.prompts.append(
+                declared_prompt(
+                    f"{name}/system_prompt",
+                    system.content,
+                    PROMPT_FORMAT_PLAIN,
+                    f"{origin}.system_prompt",
+                )
+            )
+        else:
+            context.warn(f"{origin}: system prompt {name!r} is not registered")
+    # Hook nodes (`<middleware>.before_model`, ...) and the model node's composed wrappers.
+    roots = [
+        getattr(getattr(node, "bound", None), attribute, None)
+        for node in graph.nodes.values()
+        for attribute in ("func", "afunc")
+    ]
+    for middleware in reachable_middleware(roots):
+        _dynamic(middleware, f"{origin}.middleware.{middleware.name}", found, context)
+    node = getattr(graph.nodes.get("tools"), "bound", None)
+    if isinstance(node, ToolNode):
+        found.tools += [
+            declared_tool(describe_tool(tool), f"{origin}.tools.{name}")
+            for name, tool in node.tools_by_name.items()
+        ]
+    return found
+
+
+def _dynamic(
+    middleware: AgentMiddleware[Any, Any], origin: str, found: Discovered, context: DiscoveryContext
+) -> None:
+    if dynamic_prompt_function(middleware) is None:
+        return
+    prompt = dynamic_prompt(middleware)
+    if prompt is None or not valid_prompt_name(prompt[0]):
+        context.warn(f"{origin}: dynamic prompt {middleware.name!r} could not be read")
+        return
+    found.prompts.append(declared_prompt(prompt[0], prompt[1], PROMPT_FORMAT_DYNAMIC, origin))
+
+
+def _template(
+    name: str, template: PromptTemplate, origin: str, found: Discovered, context: DiscoveryContext
+) -> None:
+    format = _FORMATS.get(template.template_format)
+    if format is None:
+        context.warn(f"{origin}: {template.template_format} templates are not registered")
+        return
+    if "{" not in template.template:
+        format = PROMPT_FORMAT_PLAIN
+    if not valid_prompt_name(name):
+        context.warn(f"{origin}: {name!r} cannot name a prompt")
+        return
+    found.prompts.append(declared_prompt(name, template.template, format, origin))
+
+
+def _chat(
+    chat: ChatPromptTemplate, origin: str, found: Discovered, context: DiscoveryContext
+) -> None:
+    for index, message in enumerate(chat.messages):
+        if isinstance(message, MessagesPlaceholder):
+            continue
+        if isinstance(message, BaseMessage):
+            if isinstance(message.content, str):
+                name = f"{context.name}/{index}.{message.type}"
+                found.prompts.append(
+                    declared_prompt(
+                        name, message.content, PROMPT_FORMAT_PLAIN, f"{origin}.messages[{index}]"
+                    )
+                )
+            continue
+        prompt = getattr(message, "prompt", None)
+        if isinstance(prompt, PromptTemplate):
+            # ChatMessagePromptTemplate has a role; the others are named for theirs.
+            role = (
+                getattr(message, "role", None)
+                or type(message).__name__.removesuffix("MessagePromptTemplate").lower()
+            )
+            name = f"{context.name}/{index}.{role}"
+            _template(name, prompt, f"{origin}.messages[{index}]", found, context)
+        else:
+            context.warn(f"{origin}.messages[{index}]: only text message templates are registered")

trytilde_langchain-3.0.1/src/tilde_langchain/messages.py

@@ -0,0 +1,201 @@
+"""Convert typed Tilde context into LangChain messages."""
+
+from __future__ import annotations
+
+import inspect
+import json
+from collections.abc import Awaitable, Callable, Iterable
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
+
+from tilde import (
+    ContextMessage,
+    ConversationMessage,
+    DownloadedAttachment,
+    GoalMessage,
+    ObjectiveMessage,
+    TaskMessage,
+)
+from tilde_langchain.attachments import AttachmentConversion, AttachmentHandler, convert_attachment
+
+Converted = BaseMessage | None
+_Handler = Callable[[Any], Converted | Awaitable[Converted]]
+
+
+@dataclass(slots=True)
+class MessageHandlers:
+    """Explicit handlers take precedence over cached and default rendering; None omits an item."""
+
+    message: Callable[[ConversationMessage], Converted | Awaitable[Converted]] | None = None
+    objective: Callable[[ObjectiveMessage], Converted | Awaitable[Converted]] | None = None
+    goal: Callable[[GoalMessage], Converted | Awaitable[Converted]] | None = None
+    task: Callable[[TaskMessage], Converted | Awaitable[Converted]] | None = None
+
+
+class _Attachments(Protocol):
+    async def download(self, attachment_id: str) -> DownloadedAttachment: ...
+
+
+class ConversionContext(Protocol):
+    """The parts of ``AgentContext`` the converter uses; a test double only needs these."""
+
+    attachments: _Attachments
+
+    async def cache_converted_messages(self, messages: list[tuple[str, Any]]) -> None: ...
+
+
+_BATCH_ITEMS = 100
+_BATCH_BYTES = 1024 * 1024
+
+
+async def convert_to_langchain_messages(
+    messages: Iterable[ContextMessage],
+    *,
+    context: ConversionContext | None = None,
+    on_message: MessageHandlers | None = None,
+    on_attachment: AttachmentHandler | None = None,
+) -> list[BaseMessage]:
+    """Convert typed SDK context into ``HumanMessage``/``AIMessage`` items, ready for an agent.
+
+    Each result carries the Tilde message id. Incomplete conversation messages are skipped
+    unless a custom ``message`` handler is supplied. Completed, attachment-free conversions are
+    cached through ``context.cache_converted_messages`` in bounded batches; attachments are
+    hydrated afresh on every run and never stored in the cache.
+    """
+    output: list[BaseMessage] = []
+    batch: list[tuple[str, Any]] = []
+    batch_bytes = 0
+
+    async def flush() -> None:
+        nonlocal batch_bytes
+        if batch and context is not None:
+            await context.cache_converted_messages(batch[:])
+        batch.clear()
+        batch_bytes = 0
+
+    for item in messages:
+        handler: _Handler | None
+        converted: Converted
+        cacheable = False
+        if isinstance(item, ObjectiveMessage):
+            handler = on_message.objective if on_message else None
+            converted = (
+                await _call(handler, item)
+                if handler
+                else HumanMessage(id=item.id, content=item.objective)
+            )
+        elif isinstance(item, GoalMessage):
+            handler = on_message.goal if on_message else None
+            converted = (
+                await _call(handler, item)
+                if handler
+                else HumanMessage(
+                    id=item.id, content=f"Goal ({item.goal.status}): {item.goal.objective}"
+                )
+            )
+        elif isinstance(item, TaskMessage):
+            handler = on_message.task if on_message else None
+            if handler:
+                converted = await _call(handler, item)
+            else:
+                text = f"Task ({item.task.status}): {item.task.title}"
+                if item.task.blocked_reason:
+                    text += f"\nBlocked: {item.task.blocked_reason}"
+                converted = HumanMessage(id=item.id, content=text)
+        else:
+            handler = on_message.message if on_message else None
+            if handler:
+                converted = await _call(handler, item)
+            elif item.message.status != "complete":
+                continue
+            else:
+                # File bytes are hydrated afresh through the scoped SDK, never from the cache.
+                hydrated = _hydrate(item) if not item.message.attachments else None
+                converted = hydrated or await _render(item, context, on_attachment)
+                # Only canonical, attachment-free chat records are cached by the runtime; work
+                # state stays a live projection and file bytes never duplicate into the cache.
+                cacheable = hydrated is None and not item.message.attachments
+        if converted is None:
+            continue
+        output.append(converted)
+        if cacheable and context is not None:
+            entry = {"id": converted.id, "role": _role(converted), "content": converted.content}
+            serialized = json.dumps(entry)
+            size = len(serialized.encode())
+            if size > _BATCH_BYTES:
+                continue
+            if len(batch) == _BATCH_ITEMS or batch_bytes + size > _BATCH_BYTES:
+                await flush()
+            batch.append((item.id, json.loads(serialized)))
+            batch_bytes += size
+    await flush()
+    return output
+
+
+async def _call(handler: _Handler, item: ContextMessage) -> Converted:
+    result = handler(item)
+    if inspect.isawaitable(result):
+        result = await result
+    return result
+
+
+async def _render(
+    item: ConversationMessage,
+    context: ConversionContext | None,
+    on_attachment: AttachmentHandler | None,
+) -> Converted:
+    blocks: list[dict[str, Any]] = []
+    if item.message.subject:
+        blocks.append({"type": "text", "text": f"Subject: {item.message.subject}"})
+    if item.message.text:
+        blocks.append({"type": "text", "text": item.message.text})
+    for attachment in item.message.attachments:
+
+        def download(attachment_id: str = attachment.id) -> Awaitable[DownloadedAttachment]:
+            if context is None:
+                raise RuntimeError(
+                    "Attachment conversion requires context or a custom on_attachment handler"
+                )
+            return context.attachments.download(attachment_id)
+
+        result = (on_attachment or convert_attachment)(
+            AttachmentConversion(message=item, attachment=attachment, download=download)
+        )
+        if inspect.isawaitable(result):
+            result = await result
+        if result is None:
+            continue
+        blocks.extend(result if isinstance(result, list) else [result])
+    if not blocks:
+        return None
+    return _message(item.role, item.id, blocks)
+
+
+def _hydrate(item: ConversationMessage) -> Converted:
+    cached = item.cached_agent_representation
+    if (
+        not isinstance(cached, dict)
+        or cached.get("id") != item.id
+        or cached.get("role") != item.role
+    ):
+        return None
+    content = cached.get("content")
+    if isinstance(content, str):
+        return _message(item.role, item.id, content)
+    if not isinstance(content, list) or not all(isinstance(block, dict) for block in content):
+        return None
+    if any(block.get("type") in ("image", "file") for block in content):
+        return None
+    return _message(item.role, item.id, content)
+
+
+def _message(role: str, id: str, content: str | list[dict[str, Any]]) -> BaseMessage:
+    if role == "assistant":
+        return AIMessage(id=id, content=content)
+    return HumanMessage(id=id, content=content)
+
+
+def _role(message: BaseMessage) -> str:
+    return "assistant" if isinstance(message, AIMessage) else "user"

trytilde_langchain-3.0.1/src/tilde_langchain/middleware.py

@@ -0,0 +1,128 @@
+"""Tilde's per-invocation pieces for a module-level ``create_agent`` graph.
+
+A compiled graph takes no per-call tools or messages: ``ainvoke``'s config carries callbacks
+and ``context`` only, and callbacks cannot change state. So the pieces come from middleware
+the agent is created with once, ``create_agent(..., middleware=[tilde_middleware(), ...])``,
+which reads the invocation running the graph from Tilde's context variable. Outside an
+invocation it does nothing.
+
+Tools added to a model request in ``wrap_model_call`` are not registered with the graph's
+``ToolNode``; ``create_agent`` allows that only when some middleware executes them in
+``wrap_tool_call`` (its "dynamic tools" contract), which this middleware does.
+"""
+
+from __future__ import annotations
+
+import weakref
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from langchain.agents.middleware import (
+    AgentMiddleware,
+    AgentState,
+    ModelRequest,
+    ModelResponse,
+)
+from langchain_core.messages import HumanMessage, SystemMessage, ToolMessage
+from langchain_core.tools import BaseTool
+from langgraph.prebuilt.tool_node import ToolCallRequest
+from langgraph.runtime import Runtime
+from langgraph.types import Command
+
+from tilde import AgentContext, BundledTools, current_invocation
+from tilde_langchain.discover import dynamic_stamp, reachable_middleware
+from tilde_langchain.tools import convert_to_langchain_tools, with_tilde_tools
+
+
+@dataclass(slots=True)
+class _Invocation:
+    tools: dict[str, BaseTool]
+    skills: str
+
+
+# One entry per running invocation; it goes when the invocation's context does.
+_invocations: weakref.WeakKeyDictionary[AgentContext, _Invocation] = weakref.WeakKeyDictionary()
+
+
+async def _invocation(ctx: AgentContext, bundled: BundledTools | None) -> _Invocation:
+    found = _invocations.get(ctx)
+    if found is None:
+        # Plain create_agent has no native skills: tools to read them plus a summary.
+        summary = await ctx.skills.summary()
+        tools = await with_tilde_tools(
+            ctx,
+            bundled.tools if bundled else [],
+            options=bundled.options if bundled else None,
+        )
+        if summary:
+            tools += convert_to_langchain_tools(ctx.skills.tools())
+        found = _invocations[ctx] = _Invocation({tool.name: tool for tool in tools}, summary)
+    return found
+
+
+class TildeMiddleware(AgentMiddleware[AgentState[Any], Any]):
+    """Before each model call: check cancellation and add steering input as user messages
+    (kept in the graph state). Around it: stamp the ``@dynamic_prompt`` middleware listed
+    after this one, add the channel's tools, the agent's other Tilde tools, its bundled tools
+    (audited and published as ``with_tilde_tools`` does) and, when skills are assigned, the
+    skill tools and their summary. Around tool calls: execute those tools."""
+
+    def __init__(self, bundled: BundledTools | None = None) -> None:
+        super().__init__()
+        self.bundled = bundled
+
+    async def abefore_model(
+        self, state: AgentState[Any], runtime: Runtime[Any]
+    ) -> dict[str, Any] | None:
+        ctx = current_invocation()
+        if ctx is None:
+            return None
+        ctx.check()
+        inputs = ctx.take_inputs()
+        if not inputs:
+            return None
+        return {"messages": [HumanMessage(content=input.text) for input in inputs]}
+
+    async def awrap_model_call(
+        self,
+        request: ModelRequest[Any],
+        handler: Callable[[ModelRequest[Any]], Awaitable[ModelResponse[Any]]],
+    ) -> ModelResponse[Any]:
+        ctx = current_invocation()
+        if ctx is None:
+            return await handler(request)
+        # `handler` runs the middleware after this one; a dynamic prompt there sets the system
+        # prompt this call sends.
+        for middleware in reachable_middleware(handler):
+            stamp = dynamic_stamp(middleware)
+            if stamp is not None:
+                ctx.activate_prompt(*stamp)
+        invocation = await _invocation(ctx, self.bundled)
+        messages = request.messages
+        if invocation.skills:
+            # A second system message right after the system prompt, which a dynamic prompt
+            # after this middleware replaces; this call only, not the graph state.
+            messages = [SystemMessage(content=invocation.skills), *messages]
+        return await handler(
+            request.override(tools=[*request.tools, *invocation.tools.values()], messages=messages)
+        )
+
+    async def awrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command[Any]]],
+    ) -> ToolMessage | Command[Any]:
+        ctx = current_invocation()
+        invocation = _invocations.get(ctx) if ctx is not None else None
+        if request.tool is None and invocation is not None:
+            tool = invocation.tools.get(request.tool_call["name"])
+            if tool is not None:
+                return await handler(request.override(tool=tool))
+        return await handler(request)
+
+
+def tilde_middleware(bundled: BundledTools | None = None) -> TildeMiddleware:
+    """Put it first in ``create_agent(middleware=[...])`` so it sees the dynamic prompts.
+    ``bundled`` is the agent's ``define_tools(...)``."""
+    return TildeMiddleware(bundled)

trytilde_langchain-3.0.1/src/tilde_langchain/tools.py

@@ -0,0 +1,181 @@
+"""Expose Tilde channel tools as LangChain tools with the model's tool-call id forwarded, and
+publish the agent's own LangChain tools to Tilde as bundled tools."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+from uuid import UUID
+
+from langchain_core.callbacks import AsyncCallbackHandler, BaseCallbackManager
+from langchain_core.messages import ToolMessage
+from langchain_core.tools import BaseTool
+from langchain_core.utils.function_calling import convert_to_openai_tool
+
+from tilde import AgentContext, BundledOptions, ChannelTool, Tool
+from tilde._tools import ToolSpec, bundled_tool, model_tool_name, tool_spec
+
+
+class ChannelToolAdapter(BaseTool):
+    """Async-only LangChain tool over one Tilde channel tool.
+
+    LangChain passes the model's tool-call id into ``BaseTool.arun`` whenever the tool is
+    invoked with a ``ToolCall`` dict (which is what LangGraph's ``ToolNode`` and therefore
+    ``create_agent`` do). With a JSON-schema ``args_schema`` nothing injects that id into the
+    coroutine arguments, so ``_to_args_and_kwargs`` is overridden to carry it into ``_arun``.
+    When invoked directly with plain arguments there is no call id; ``ChannelTool.execute``
+    then generates a random UUID, so the call is audited but not deduplicated.
+    """
+
+    channel: ChannelTool | Tool
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    def _to_args_and_kwargs(
+        self, tool_input: str | dict[str, Any], tool_call_id: str | None
+    ) -> tuple[tuple[str, ...], dict[str, Any]]:
+        return (), {"input": tool_input, "tool_call_id": tool_call_id}
+
+    def _run(self, *args: Any, **kwargs: Any) -> Any:
+        raise NotImplementedError("Channel tools run on the agent's event loop; use ainvoke")
+
+    async def _arun(self, input: Any, tool_call_id: str | None = None) -> Any:
+        return await self.channel.execute(input, tool_call_id=tool_call_id)
+
+
+def convert_to_langchain_tools(
+    channels: Mapping[str, ChannelTool | Tool],
+    *,
+    instructions: Mapping[str, str] | None = None,
+    prefix: str = "",
+) -> list[BaseTool]:
+    """Preserve provider schemas and descriptions; ``instructions`` overrides descriptions
+    without touching schemas or authorization, ``prefix`` namespaces model tool names.
+    ``ctx.skills.tools()`` converts the same way."""
+    result: dict[str, BaseTool] = {}
+    for name, channel in channels.items():
+        key = model_tool_name(f"{prefix}{name}")
+        if not key or key in result:
+            raise ValueError("Conflicting or invalid model tool names")
+        description = (
+            instructions[name]
+            if instructions is not None and name in instructions
+            else channel.description
+        )
+        result[key] = ChannelToolAdapter(
+            name=key,
+            description=description,
+            args_schema=channel.input_schema,
+            channel=channel,
+        )
+    return list(result.values())
+
+
+async def with_tilde_tools(
+    ctx: AgentContext,
+    native_tools: Sequence[BaseTool],
+    *,
+    options: Mapping[str, BundledOptions] | None = None,
+) -> list[BaseTool]:
+    """The current channel's tools, the agent's other Tilde tools and its own tools, for
+    ``create_agent(tools=...)`` or a ``ToolNode``.
+
+    Each native tool (``@tool``, ``StructuredTool`` or any ``BaseTool``) is published to Tilde
+    with its name, description and the argument schema the model sees, so ``tools.search``
+    finds it and a ``tools.execute`` naming it runs it here. It is returned as a copy of the
+    same type with an audit callback handler attached, so ``ToolNode`` injection keeps working
+    and every call is audited once with the model's call id. Tilde metadata comes from
+    ``metadata={"tilde": BundledOptions(...)}`` or ``options[name]``, which wins. Call it once per
+    invocation.
+
+    Caveats: LangChain has no output schema, and audits record the tool message content. A
+    tool that needs ``ToolRuntime`` or ``InjectedState`` only gets them from ``ToolNode``, so it
+    cannot run through ``tools.execute``. Invoked without a ``ToolCall`` (no model call id) the
+    call is audited under LangChain's run id.
+    """
+    tools = convert_to_langchain_tools({**ctx.channel.current, **ctx.agent_tools})
+    names = {tool.name for tool in tools}
+    definitions = {}
+    for native in native_tools:
+        if native.name in names:
+            raise ValueError(f"Tool {native.name} conflicts with another tool")
+        names.add(native.name)
+        tool = _audited(ctx, native)
+        definitions[tool.name] = bundled_tool(describe_tool(native, options), _route(tool))
+        tools.append(tool)
+    # Published even when empty, so tools removed since the last call stop running here.
+    await ctx._set_bundled_tools(definitions)
+    return tools
+
+
+def describe_tool(tool: BaseTool, options: Mapping[str, BundledOptions] | None = None) -> ToolSpec:
+    """What ``with_tilde_tools`` publishes and ``tilde deploy`` declares for one tool."""
+    return tool_spec(
+        tool.name,
+        tool.description,
+        convert_to_openai_tool(tool)["function"]["parameters"],
+        options=(options or {}).get(tool.name, (tool.metadata or {}).get("tilde")),
+    )
+
+
+class _Audit(AsyncCallbackHandler):
+    """Reports one tool's calls. Attached to that tool only, it is not inherited by child runs;
+    ``raise_error`` surfaces failed reports instead of LangChain logging them."""
+
+    raise_error = True
+
+    def __init__(self, ctx: AgentContext, name: str) -> None:
+        self._ctx = ctx
+        self._name = name
+        self._calls: dict[UUID, str] = {}
+
+    async def on_tool_start(
+        self,
+        serialized: dict[str, Any],
+        input_str: str,
+        *,
+        run_id: UUID,
+        inputs: dict[str, Any] | None = None,
+        tool_call_id: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        call = self._calls[run_id] = tool_call_id or str(run_id)
+        input = inputs if inputs is not None else input_str
+        await self._ctx._report_bundled(self._name, call, "running", input=input)
+
+    async def on_tool_end(self, output: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        call = self._calls.pop(run_id, str(run_id))
+        # A ToolMessage with error status is a failure LangChain handled for the model.
+        if isinstance(output, ToolMessage) and output.status == "error":
+            await self._ctx._report_bundled(self._name, call, "failed", error=str(output.content))
+            return
+        content = output.content if isinstance(output, ToolMessage) else output
+        await self._ctx._report_bundled(self._name, call, "completed", output=content)
+
+    async def on_tool_error(self, error: BaseException, *, run_id: UUID, **kwargs: Any) -> None:
+        call = self._calls.pop(run_id, str(run_id))
+        await self._ctx._report_bundled(self._name, call, "failed", error=str(error))
+
+
+def _audited(ctx: AgentContext, tool: BaseTool) -> BaseTool:
+    # Not a proxy: a copy of the tool itself keeps its type, schema and injected arguments.
+    handler = _Audit(ctx, tool.name)
+    callbacks = tool.callbacks
+    if isinstance(callbacks, BaseCallbackManager):
+        callbacks = callbacks.copy()
+        callbacks.add_handler(handler, inherit=False)
+    else:
+        callbacks = [*(callbacks or []), handler]
+    return tool.model_copy(update={"callbacks": callbacks})
+
+
+def _route(tool: BaseTool):
+    # A tools.execute naming this tool invokes it with a ToolCall carrying the tools.execute
+    # call id; it runs inside that call's LangChain config, so traces nest.
+    async def execute(input: Any, call: str) -> Any:
+        result = await tool.ainvoke(
+            {"type": "tool_call", "id": call, "name": tool.name, "args": input}
+        )
+        return result.content if isinstance(result, ToolMessage) else result
+
+    return execute