trytilde-agno 3.0.1__tar.gz

trytilde_agno-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_agno-3.0.1/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: trytilde-agno
+Version: 3.0.1
+Summary: Tilde adapter for Agno: convert invocation history to Agno messages and channel tools to Agno functions
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: agno<4,>=3
+Requires-Dist: trytilde
+Description-Content-Type: text/markdown
+
+# Agno adapter
+
+Core history and delivery live in `trytilde`. This package converts typed context to
+Agno messages and channel tools to Agno functions, bundles an invocation's run options in
+`tilde_agno(ctx, agent)`, serves registry skills through `TildeSkills` and lets `tilde deploy`
+register module-level agents and teams.
+
+```python
+import tilde
+from agno.agent import Agent
+from agno.models.openai import OpenAIChat
+from agno.skills import LocalSkills
+from tilde_agno import TildeSkills, convert_to_agno_messages, tilde_agno
+
+INFERENCE = tilde.inference("default")
+responder = Agent(
+    model=OpenAIChat(
+        id="gpt-4o-mini",
+        base_url=INFERENCE.base_url,
+        api_key=INFERENCE.api_key,
+        http_client=INFERENCE.async_client(),
+    ),
+    instructions="Respond using the current channel's tools. Returned model text is private.",
+    skills=TildeSkills([LocalSkills("skills")]),
+    tool_call_limit=8,
+    telemetry=False,
+)
+
+
+async def run(ctx):
+    history = await ctx.message.history()
+    messages = await convert_to_agno_messages(history.items, context=ctx)
+    await responder.arun(input=messages, **await tilde_agno(ctx, responder))
+```
+
+`tilde_agno` returns `run_context` (with the current channel's tools as Agno's per-run
+`client_tools`), a `run_id` that a stop or suspension cancels, and the thread as `session_id`.
+Agno has no per-step message hook, so input steered while the agent works is appended to the
+next Tilde tool result by a tool hook (an agent-level `tool_hooks` replaces it). Dynamic
+`instructions`, `description` or `system_message` stamp the invocation's model calls.
+`TildeSkills` is Agno's `Skills` plus the skills assigned to the agent in Tilde, loaded for each
+invocation from `ctx.skills.directory()`; with plain `Skills` (or none) the registry skills come
+as `list_skills`/`read_skill` tools with their summary in the system message.
+
+`tilde deploy` (entry point `tilde.discover`) registers each module-level `Agent`/`Team`:
+`<name or variable>/instructions` (`/<n>` from 1 for a list), `/description` and
+`/system_message`, plain or braces when `{var}` is resolved in context, dynamic (the function's
+source) for callables; `LocalSkills` folders ship with the deployment.
+
+The converted list is passed as the run input. Agno appends a `list[Message]` input verbatim
+after its own system message, so roles and media survive and Tilde remains the source of
+history; leave `add_history_to_context` off. `tool_call_limit` caps tool-call rounds: once
+reached, further calls receive an error result instead of executing.
+
+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 receive the assistant
+role.
+
+Images and PDFs are downloaded through `ctx.attachments.download` and attached as Agno
+`Image`/`File` media. 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 agno.models.message import Message
+from tilde_agno import MessageHandlers
+
+history = await ctx.message.history(include_work=True)
+messages = await convert_to_agno_messages(
+    history.items,
+    context=ctx,
+    on_message=MessageHandlers(
+        goal=lambda item: Message(
+            id=item.id, role="user", content=f"Our goal: {item.goal.objective}"
+        ),
+        task=lambda item: None,  # Omit this type, or provide a different rendering.
+    ),
+    on_attachment=decode_your_format,  # (conversion) -> str | Image | File | list | None
+)
+```
+
+`MessageHandlers` supports `message`, `objective`, `goal`, and `task`; handlers 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. Completed
+conversation conversions use the existing per-agent cache, in bounded batches. Files are
+hydrated afresh and are never stored in the cache; objectives/goals/tasks remain live
+projections rather than cached chat records.
+
+## Channel tools
+
+`convert_to_agno_tools(ctx.channel.current)` preserves the provider's descriptions and JSON
+schemas (`skip_entrypoint_processing` keeps Agno from introspecting a replacement schema) and
+forwards the model's tool-call id to Tilde's audited tool execution. Agno injects the running
+`FunctionCall` into the entrypoint's `fc` parameter; its `call_id` is the id the model chose.
+The adapter does not publish the model's final text. The agent chooses the provider tool and
+arguments, including routing fields required by that provider.
+
+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
+conflicts raise.
+
+The core SDK exposes typed callable tools on `ctx.channel.slack`, `github`, `agentmail`,
+`linq`, `whatsapp`, `telnyx_whatsapp`, and `native`. Use `ctx.channel.connections()` and
+`ctx.channel.for_connection(id)` when multiple connections use a provider.
+
+## Bundled tools
+
+The agent's own Agno tools join Tilde's with one call:
+
+```python
+from tilde import BundledOptions
+from tilde_agno import with_tilde_tools
+
+
+def roll_dice(count: int = 1) -> list[int]:
+    """Roll six-sided dice."""
+    return [random.randint(1, 6) for _ in range(count)]
+
+
+tools = await with_tilde_tools(
+    ctx, [roll_dice], options={"roll_dice": BundledOptions(summary="Rolled dice")}
+)
+agent = Agent(model=model, tools=tools)
+await agent.arun(input=messages)
+```
+
+`with_tilde_tools` takes plain functions, `@tool` functions and toolkits and returns the
+current channel's tools, `ctx.agent_tools` and copies of the native functions. It publishes the
+native tools to Tilde with their parameter schema and MCP `annotations` hints, so
+`tools.search` finds them and a `tools.execute` naming one runs it here as the same agent. Every
+call is audited once with the model's call id by `pre_hook`/`post_hook`, chained around the
+tool's own hooks; the entrypoint is untouched, so Agno's argument injection keeps working. Agno
+has no free metadata or output schema, so summaries come from `options`. Run with `arun`: the
+audit hooks are async. Agno swallows hook errors, so a failed audit never fails the call, and
+toolkit-level instructions are not carried over.

trytilde_agno-3.0.1/README.md

@@ -0,0 +1,138 @@
+# Agno adapter
+
+Core history and delivery live in `trytilde`. This package converts typed context to
+Agno messages and channel tools to Agno functions, bundles an invocation's run options in
+`tilde_agno(ctx, agent)`, serves registry skills through `TildeSkills` and lets `tilde deploy`
+register module-level agents and teams.
+
+```python
+import tilde
+from agno.agent import Agent
+from agno.models.openai import OpenAIChat
+from agno.skills import LocalSkills
+from tilde_agno import TildeSkills, convert_to_agno_messages, tilde_agno
+
+INFERENCE = tilde.inference("default")
+responder = Agent(
+    model=OpenAIChat(
+        id="gpt-4o-mini",
+        base_url=INFERENCE.base_url,
+        api_key=INFERENCE.api_key,
+        http_client=INFERENCE.async_client(),
+    ),
+    instructions="Respond using the current channel's tools. Returned model text is private.",
+    skills=TildeSkills([LocalSkills("skills")]),
+    tool_call_limit=8,
+    telemetry=False,
+)
+
+
+async def run(ctx):
+    history = await ctx.message.history()
+    messages = await convert_to_agno_messages(history.items, context=ctx)
+    await responder.arun(input=messages, **await tilde_agno(ctx, responder))
+```
+
+`tilde_agno` returns `run_context` (with the current channel's tools as Agno's per-run
+`client_tools`), a `run_id` that a stop or suspension cancels, and the thread as `session_id`.
+Agno has no per-step message hook, so input steered while the agent works is appended to the
+next Tilde tool result by a tool hook (an agent-level `tool_hooks` replaces it). Dynamic
+`instructions`, `description` or `system_message` stamp the invocation's model calls.
+`TildeSkills` is Agno's `Skills` plus the skills assigned to the agent in Tilde, loaded for each
+invocation from `ctx.skills.directory()`; with plain `Skills` (or none) the registry skills come
+as `list_skills`/`read_skill` tools with their summary in the system message.
+
+`tilde deploy` (entry point `tilde.discover`) registers each module-level `Agent`/`Team`:
+`<name or variable>/instructions` (`/<n>` from 1 for a list), `/description` and
+`/system_message`, plain or braces when `{var}` is resolved in context, dynamic (the function's
+source) for callables; `LocalSkills` folders ship with the deployment.
+
+The converted list is passed as the run input. Agno appends a `list[Message]` input verbatim
+after its own system message, so roles and media survive and Tilde remains the source of
+history; leave `add_history_to_context` off. `tool_call_limit` caps tool-call rounds: once
+reached, further calls receive an error result instead of executing.
+
+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 receive the assistant
+role.
+
+Images and PDFs are downloaded through `ctx.attachments.download` and attached as Agno
+`Image`/`File` media. 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 agno.models.message import Message
+from tilde_agno import MessageHandlers
+
+history = await ctx.message.history(include_work=True)
+messages = await convert_to_agno_messages(
+    history.items,
+    context=ctx,
+    on_message=MessageHandlers(
+        goal=lambda item: Message(
+            id=item.id, role="user", content=f"Our goal: {item.goal.objective}"
+        ),
+        task=lambda item: None,  # Omit this type, or provide a different rendering.
+    ),
+    on_attachment=decode_your_format,  # (conversion) -> str | Image | File | list | None
+)
+```
+
+`MessageHandlers` supports `message`, `objective`, `goal`, and `task`; handlers 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. Completed
+conversation conversions use the existing per-agent cache, in bounded batches. Files are
+hydrated afresh and are never stored in the cache; objectives/goals/tasks remain live
+projections rather than cached chat records.
+
+## Channel tools
+
+`convert_to_agno_tools(ctx.channel.current)` preserves the provider's descriptions and JSON
+schemas (`skip_entrypoint_processing` keeps Agno from introspecting a replacement schema) and
+forwards the model's tool-call id to Tilde's audited tool execution. Agno injects the running
+`FunctionCall` into the entrypoint's `fc` parameter; its `call_id` is the id the model chose.
+The adapter does not publish the model's final text. The agent chooses the provider tool and
+arguments, including routing fields required by that provider.
+
+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
+conflicts raise.
+
+The core SDK exposes typed callable tools on `ctx.channel.slack`, `github`, `agentmail`,
+`linq`, `whatsapp`, `telnyx_whatsapp`, and `native`. Use `ctx.channel.connections()` and
+`ctx.channel.for_connection(id)` when multiple connections use a provider.
+
+## Bundled tools
+
+The agent's own Agno tools join Tilde's with one call:
+
+```python
+from tilde import BundledOptions
+from tilde_agno import with_tilde_tools
+
+
+def roll_dice(count: int = 1) -> list[int]:
+    """Roll six-sided dice."""
+    return [random.randint(1, 6) for _ in range(count)]
+
+
+tools = await with_tilde_tools(
+    ctx, [roll_dice], options={"roll_dice": BundledOptions(summary="Rolled dice")}
+)
+agent = Agent(model=model, tools=tools)
+await agent.arun(input=messages)
+```
+
+`with_tilde_tools` takes plain functions, `@tool` functions and toolkits and returns the
+current channel's tools, `ctx.agent_tools` and copies of the native functions. It publishes the
+native tools to Tilde with their parameter schema and MCP `annotations` hints, so
+`tools.search` finds them and a `tools.execute` naming one runs it here as the same agent. Every
+call is audited once with the model's call id by `pre_hook`/`post_hook`, chained around the
+tool's own hooks; the entrypoint is untouched, so Agno's argument injection keeps working. Agno
+has no free metadata or output schema, so summaries come from `options`. Run with `arun`: the
+audit hooks are async. Agno swallows hook errors, so a failed audit never fails the call, and
+toolkit-level instructions are not carried over.

trytilde_agno-3.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "trytilde-agno"
+version = "3.0.1"
+description = "Tilde adapter for Agno: convert invocation history to Agno messages and channel tools to Agno functions"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+dependencies = ["trytilde", "agno>=3,<4"]
+
+# `tilde deploy` reads module-level agents' prompts (and skill folders) through this discoverer.
+[project.entry-points."tilde.discover"]
+agno = "tilde_agno.discover:discover"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tilde_agno"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/tilde_agno", "README.md"]

trytilde_agno-3.0.1/src/tilde_agno/__init__.py

@@ -0,0 +1,32 @@
+"""Tilde adapter for Agno: typed context to Agno messages, channel tools to Agno functions, the
+per-run ``tilde_agno`` options, registry skills through ``TildeSkills`` and ``tilde deploy``
+discovery of module-level agents and teams."""
+
+from tilde_agno.attachments import (
+    AttachmentConversion,
+    AttachmentHandler,
+    AttachmentPart,
+    AttachmentResult,
+    convert_attachment,
+    normalize_media_type,
+)
+from tilde_agno.discover import discover
+from tilde_agno.invocation import TildeSkills, tilde_agno
+from tilde_agno.messages import MessageHandlers, convert_to_agno_messages
+from tilde_agno.tools import convert_to_agno_tools, with_tilde_tools
+
+__all__ = [
+    "AttachmentConversion",
+    "AttachmentHandler",
+    "AttachmentPart",
+    "AttachmentResult",
+    "MessageHandlers",
+    "TildeSkills",
+    "convert_attachment",
+    "convert_to_agno_messages",
+    "convert_to_agno_tools",
+    "discover",
+    "normalize_media_type",
+    "tilde_agno",
+    "with_tilde_tools",
+]

trytilde_agno-3.0.1/src/tilde_agno/attachments.py

@@ -0,0 +1,75 @@
+"""Default attachment hydration: images and PDFs become Agno media, text files become text."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+from agno.media import File, Image
+
+from tilde import ConversationMessage, DownloadedAttachment
+from tilde.types.v1.chat_pb2 import Attachment
+
+AttachmentPart = str | Image | File
+AttachmentResult = AttachmentPart | list[AttachmentPart] | None
+
+
+@dataclass(slots=True)
+class AttachmentConversion:
+    message: ConversationMessage
+    attachment: Attachment
+    # Uses the current invocation's authenticated, thread-scoped attachment API.
+    download: Callable[[], Awaitable[DownloadedAttachment]]
+
+
+AttachmentHandler = Callable[[AttachmentConversion], AttachmentResult | Awaitable[AttachmentResult]]
+
+_TEXT_TYPES = {"application/json", "application/xml"}
+_IMAGE_TYPES = {"image/jpeg", "image/png", "image/gif", "image/webp"}
+_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",
+}
+
+
+async def convert_attachment(input: AttachmentConversion) -> AttachmentResult:
+    """Hydrate images/PDFs as Agno media and textual files as their 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
+    image = media_type in _IMAGE_TYPES
+    if not text and not image and media_type != "application/pdf":
+        return (
+            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:
+        return f"Attached file: {attachment.filename}\n{result.content.decode('utf-8', 'replace')}"
+    if image:
+        return Image(
+            content=result.content, mime_type=media_type, format=media_type.removeprefix("image/")
+        )
+    return File(
+        content=result.content, mime_type=media_type, filename=attachment.filename, format="pdf"
+    )
+
+
+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_agno-3.0.1/src/tilde_agno/discover.py

@@ -0,0 +1,133 @@
+"""``tilde deploy`` discovery for Agno (entry point ``tilde.discover``).
+
+A module-level ``Agent`` or ``Team`` registers, named after ``name`` (else its variable):
+``<name>/instructions`` (``/<n>`` from 1 for a list), ``<name>/description`` and
+``<name>/system_message``. Text is plain, or braces when it holds a ``{var}`` Agno resolves
+from session state and dependencies (``resolve_in_context``, on by default); a function is
+dynamic with its source as the template, stamped at runtime by ``tilde_agno``. Folders of
+``LocalSkills`` loaders in ``skills`` ship with the deployment. Functions and toolkits in
+``tools`` are declared as ``with_tilde_tools`` publishes them, as is a ``define_tools`` value of
+Agno tools, or of plain functions when the project imports Agno. Nothing is run.
+"""
+
+from __future__ import annotations
+
+import inspect
+import re
+import sys
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any
+
+from agno.agent import Agent
+from agno.models.message import Message
+from agno.skills import LocalSkills, Skills
+from agno.team import Team
+from agno.tools.function import Function
+from agno.tools.toolkit import Toolkit
+
+from tilde import BundledOptions, BundledTools
+from tilde.discovery import (
+    PROMPT_FORMAT_BRACES,
+    PROMPT_FORMAT_DYNAMIC,
+    PROMPT_FORMAT_PLAIN,
+    Discovered,
+    DiscoveryContext,
+    declared_prompt,
+    declared_tool,
+)
+from tilde.management.v1.deployments_pb2 import DeclaredPrompt, DeclaredTool
+from tilde.prompts import valid_prompt_name
+from tilde.skills import SkillDefinition, read_skill, read_skills
+from tilde_agno.tools import describe_tool, functions_of, processed
+
+_VARIABLE = re.compile(r"\{[A-Za-z_][A-Za-z0-9_]*\}")
+
+
+def discover(value: Any, context: DiscoveryContext) -> Discovered | None:
+    if isinstance(value, BundledTools):
+        if not value.tools or not all(_readable(tool) for tool in value.tools):
+            return None
+        # Plain functions alone could be another framework's.
+        ours = {"agno", "tilde_agno"} & context.imported or any(
+            not inspect.isroutine(tool) for tool in value.tools
+        )
+        if not ours:
+            return None
+        return Discovered(tools=_tools(value.tools, value.options, f"{context.origin()}.tools"))
+    if not isinstance(value, Agent | Team):
+        return None
+    file = Path(sys.modules[context.module].__file__ or "")
+    origin = f"{context.relative(file)}#{context.name}"
+    # `tools` may also be a factory called per run; dict tool definitions are skipped too.
+    tools = list(value.tools) if isinstance(value.tools, list | tuple) else []
+    return Discovered(
+        prompts=agent_prompts(value, value.name or context.name, origin, context.warn),
+        skills=_skills(value.skills, f"{origin}.skills", context),
+        tools=_tools([tool for tool in tools if _readable(tool)], None, f"{origin}.tools"),
+    )
+
+
+def _readable(tool: Any) -> bool:
+    return isinstance(tool, Function | Toolkit) or inspect.isroutine(tool)
+
+
+def _tools(
+    tools: list[Any], options: Mapping[str, BundledOptions] | None, origin: str
+) -> list[DeclaredTool]:
+    declared = []
+    for function in functions_of(tools):
+        spec = describe_tool(processed(function), options)
+        declared.append(declared_tool(spec, f"{origin}.{spec.name}"))
+    return declared
+
+
+def agent_prompts(
+    agent: Agent | Team, name: str, origin: str, warn: Callable[[str], None]
+) -> list[DeclaredPrompt]:
+    """The agent's prompts; ``tilde_agno`` calls this again at runtime for the stamps."""
+    if not valid_prompt_name(name):
+        warn(f"Agno agent {name!r} cannot name a prompt; set name= ({origin})")
+        return []
+    # (prompt name suffix, attribute for the origin, value)
+    fields: list[tuple[str, str, Any]] = []
+    if isinstance(agent.instructions, list) and len(agent.instructions) > 1:
+        for index, text in enumerate(agent.instructions):
+            fields.append((f"instructions/{index + 1}", f"instructions[{index}]", text))
+    elif isinstance(agent.instructions, list):
+        fields.append(("instructions", "instructions", next(iter(agent.instructions), None)))
+    else:
+        fields.append(("instructions", "instructions", agent.instructions))
+    fields.append(("description", "description", agent.description))
+    system = agent.system_message
+    system = system.content if isinstance(system, Message) else system
+    fields.append(("system_message", "system_message", system))
+    prompts = []
+    for field, attribute, value in fields:
+        where = f"{origin}.{attribute}"
+        if isinstance(value, str) and value:
+            braces = agent.resolve_in_context and _VARIABLE.search(value)
+            format = PROMPT_FORMAT_BRACES if braces else PROMPT_FORMAT_PLAIN
+            prompts.append(declared_prompt(f"{name}/{field}", value, format, where))
+        elif callable(value):
+            try:
+                source = inspect.getsource(value)
+            except (OSError, TypeError):
+                warn(f"{where}: the source of {name}/{field} could not be read; not registered")
+                continue
+            prompts.append(declared_prompt(f"{name}/{field}", source, PROMPT_FORMAT_DYNAMIC, where))
+        elif value is not None and value != "":
+            warn(f"{where}: unsupported {type(value).__name__}; not registered")
+    return prompts
+
+
+def _skills(skills: Skills | None, origin: str, context: DiscoveryContext) -> list[SkillDefinition]:
+    found: list[SkillDefinition] = []
+    for loader in skills.loaders if skills is not None else []:
+        if not isinstance(loader, LocalSkills):
+            context.warn(f"{origin}: {type(loader).__name__} skills are not shipped")
+            continue
+        # LocalSkills takes a skill folder or a directory of them, resolved at construction.
+        path = loader.path
+        found.extend([read_skill(path)] if (path / "SKILL.md").is_file() else read_skills(path))
+    return found

trytilde_agno-3.0.1/src/tilde_agno/invocation.py

@@ -0,0 +1,124 @@
+"""The per-invocation pieces of an Agno run, as ``agent.arun`` keyword arguments."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+import uuid
+from collections.abc import Awaitable, Callable
+from contextvars import ContextVar
+from typing import Any
+
+from agno.agent import Agent
+from agno.run import RunContext
+from agno.run.cancel import cancel_run
+from agno.skills import LocalSkills, Skill, Skills
+from agno.team import Team
+
+from tilde import AgentContext, BundledTools
+from tilde.discovery import PROMPT_FORMAT_DYNAMIC
+from tilde_agno.discover import agent_prompts
+from tilde_agno.tools import convert_to_agno_tools, with_tilde_tools
+
+_registry: ContextVar[dict[str, Skill] | None] = ContextVar("tilde_agno_skills", default=None)
+
+
+class TildeSkills(Skills):
+    """Agno ``Skills`` that also serve the skills assigned to the agent in Tilde.
+
+    Use it in place of ``Skills``: ``Agent(skills=TildeSkills([LocalSkills("skills")]))``.
+    ``tilde_agno`` loads the invocation's registry skills (assigned in Tilde, not shipped with
+    the deployment) before each run, so a skill assigned in the UI reaches the next invocation;
+    the agent's own skills win a name clash. Agno reads loaded skills from ``Skills._skills``
+    (3.0.10), which this class resolves per invocation.
+    """
+
+    @property
+    def _skills(self) -> dict[str, Skill]:
+        own = self.__dict__["_own"]
+        registry = _registry.get()
+        return {**registry, **own} if registry else own
+
+    @_skills.setter
+    def _skills(self, value: dict[str, Skill]) -> None:
+        self.__dict__["_own"] = value
+
+    def reload(self) -> None:
+        # Reload the agent's own skills, never an invocation's merged view.
+        token = _registry.set(None)
+        try:
+            super().reload()
+        finally:
+            _registry.reset(token)
+
+
+async def tilde_agno(
+    ctx: AgentContext, agent: Agent | Team, *, bundled: BundledTools | None = None
+) -> dict[str, Any]:
+    """``await agent.arun(input, **await tilde_agno(ctx, agent, bundled=TOOLS))``.
+
+    - ``run_context.client_tools``: the current channel's tools, the agent's other Tilde tools
+      and its bundled tools (``bundled``, from ``define_tools``, audited and published as
+      ``with_tilde_tools`` does), added to the agent's own for this run (Agno's per-run tools,
+      as AG-UI frontend tools use them).
+    - Steering: a tool hook on those tools appends input steered while the agent works to the
+      tool result the model reads next. Agno has no per-step message hook, so steering waits for
+      a Tilde tool call; an agent-level ``tool_hooks`` replaces this hook.
+    - ``run_id``: registered so a stop or suspension cancels the run (``agno.run.cancel``).
+    - Dynamic instructions, description or system message stamp this invocation's model calls.
+    - Registry skills: through ``TildeSkills`` when the agent uses it, else as ``list_skills``
+      and ``read_skill`` tools with their summary in the system message.
+    """
+    tools = await with_tilde_tools(
+        ctx,
+        bundled.tools if bundled else [],
+        options=bundled.options if bundled else None,
+    )
+    if isinstance(agent.skills, TildeSkills):
+        directory = LocalSkills(await ctx.skills.directory(), validate=False)
+        _registry.set({skill.name: skill for skill in await asyncio.to_thread(directory.load)})
+    else:
+        summary = await ctx.skills.summary()
+        if summary:
+            skill_tools = convert_to_agno_tools(ctx.skills.tools())
+            # Agno adds a function's instructions to the system message for the run.
+            skill_tools[0].instructions = summary  # list_skills
+            skill_tools[0].add_instructions = True
+            tools += skill_tools
+    steering = _steering(ctx)
+    for tool in tools:
+        tool.tool_hooks = [steering]
+
+    fields = (agent.instructions, agent.description, agent.system_message)
+    name = agent.name or (_variable(agent) if any(callable(f) for f in fields) else None)
+    for prompt in agent_prompts(agent, name, "", lambda _: None) if name else []:
+        if prompt.format == PROMPT_FORMAT_DYNAMIC:
+            ctx.activate_prompt(prompt.name, prompt.hash)
+
+    run_id = str(uuid.uuid4())
+    ctx.cancellation.on_abort(lambda: cancel_run(run_id))
+    run_context = RunContext(run_id=run_id, session_id=ctx.thread_id, client_tools=tools)
+    return {"run_id": run_id, "session_id": ctx.thread_id, "run_context": run_context}
+
+
+def _steering(ctx: AgentContext) -> Callable[..., Awaitable[Any]]:
+    async def steer(function_call: Callable[..., Awaitable[Any]], arguments: dict[str, Any]) -> Any:
+        result = await function_call(**arguments)
+        inputs = ctx.take_inputs()
+        if not inputs:
+            return result
+        text = result if isinstance(result, str) else json.dumps(result, default=str)
+        steered = "\n".join(f"- {steered.text}" for steered in inputs)
+        return f"{text}\n\nNew messages arrived while you were working:\n{steered}"
+
+    return steer
+
+
+def _variable(agent: Agent | Team) -> str | None:
+    # Discovery names an unnamed agent after its module-level variable; find the same one.
+    for module in list(sys.modules.values()):
+        for key, value in list(getattr(module, "__dict__", {}).items()):
+            if value is agent and not key.startswith("_"):
+                return key
+    return None

trytilde_agno-3.0.1/src/tilde_agno/messages.py

@@ -0,0 +1,191 @@
+"""Convert typed Tilde context into Agno messages.
+
+Pass the result as ``await agent.arun(input=messages)``: Agno appends a ``list[Message]`` input
+verbatim after its system message, so roles and media survive and no separate "latest text"
+needs to be extracted. Keep ``add_history_to_context`` off; Tilde owns the history.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+from collections.abc import Awaitable, Callable, Iterable
+from dataclasses import dataclass
+from typing import Any
+
+from agno.media import File, Image
+from agno.models.message import Message
+
+from tilde import (
+    AgentContext,
+    ContextMessage,
+    ConversationMessage,
+    GoalMessage,
+    ObjectiveMessage,
+    TaskMessage,
+)
+from tilde_agno.attachments import AttachmentConversion, AttachmentHandler, convert_attachment
+
+Converted = Message | None | Awaitable[Message | None]
+
+
+@dataclass(slots=True)
+class MessageHandlers:
+    """Explicit handlers take precedence over cached and default rendering; None omits an item."""
+
+    message: Callable[[ConversationMessage], Converted] | None = None
+    objective: Callable[[ObjectiveMessage], Converted] | None = None
+    goal: Callable[[GoalMessage], Converted] | None = None
+    task: Callable[[TaskMessage], Converted] | None = None
+
+
+_BATCH_ITEMS = 100
+_BATCH_BYTES = 1024 * 1024
+
+
+async def convert_to_agno_messages(
+    messages: Iterable[ContextMessage],
+    *,
+    context: AgentContext | None = None,
+    on_message: MessageHandlers | None = None,
+    on_attachment: AttachmentHandler | None = None,
+) -> list[Message]:
+    """Convert typed SDK context into ``agno.models.message.Message`` values."""
+    output: list[Message] = []
+    handlers = on_message or MessageHandlers()
+    cache: list[tuple[str, Any]] = []
+    cache_bytes = 0
+
+    async def flush() -> None:
+        nonlocal cache_bytes
+        if cache and context is not None:
+            await context.cache_converted_messages(cache[:])
+            cache.clear()
+        cache_bytes = 0
+
+    for item in messages:
+        hydrated = False
+        if isinstance(item, ObjectiveMessage):
+            converted = (
+                await _call(handlers.objective, item)
+                if handlers.objective
+                else Message(id=item.id, role="user", content=item.objective)
+            )
+        elif isinstance(item, GoalMessage):
+            converted = (
+                await _call(handlers.goal, item)
+                if handlers.goal
+                else Message(
+                    id=item.id,
+                    role="user",
+                    content=f"Goal ({item.goal.status}): {item.goal.objective}",
+                )
+            )
+        elif isinstance(item, TaskMessage):
+            if handlers.task:
+                converted = await _call(handlers.task, item)
+            else:
+                text = f"Task ({item.task.status}): {item.task.title}"
+                if item.task.blocked_reason:
+                    text += f"\nBlocked: {item.task.blocked_reason}"
+                converted = Message(id=item.id, role="user", content=text)
+        else:
+            if item.message.status != "complete" and handlers.message is None:
+                continue
+            if handlers.message:
+                converted = await _call(handlers.message, item)
+            else:
+                # File bytes are hydrated afresh through the scoped SDK, never from the cache.
+                converted = _hydrate(item) if not item.message.attachments else None
+                hydrated = converted is not None
+                if converted is None:
+                    converted = await _render(item, context, on_attachment)
+        if converted is None:
+            continue
+        output.append(converted)
+        # Only canonical, text-only conversation messages are cached. Work state is always
+        # current, and hydrated files must not duplicate attachment bytes in the cache.
+        if (
+            context is not None
+            and isinstance(item, ConversationMessage)
+            and item.message.status == "complete"
+            and not hydrated
+            and not item.message.attachments
+            and isinstance(converted.content, str)
+            and not (converted.images or converted.files or converted.audio or converted.videos)
+        ):
+            entry = {"id": converted.id, "role": converted.role, "content": converted.content}
+            size = len(json.dumps(entry).encode())
+            if size > _BATCH_BYTES:
+                continue
+            if len(cache) == _BATCH_ITEMS or cache_bytes + size > _BATCH_BYTES:
+                await flush()
+            cache.append((item.id, entry))
+            cache_bytes += size
+    await flush()
+    return output
+
+
+async def _call(handler: Callable[[Any], Any], value: Any) -> Any:
+    result = handler(value)
+    return await result if inspect.isawaitable(result) else result
+
+
+def _hydrate(item: ConversationMessage) -> Message | None:
+    cached = item.cached_agent_representation
+    if not isinstance(cached, dict):
+        return None
+    content = cached.get("content")
+    if cached.get("id") != item.id or cached.get("role") != item.role:
+        return None
+    if not isinstance(content, str):
+        return None
+    return Message(id=item.id, role=item.role, content=content)
+
+
+def _downloader(context: AgentContext | None, attachment_id: str):
+    def download():
+        if context is None:
+            raise RuntimeError(
+                "Attachment conversion requires context or a custom on_attachment handler"
+            )
+        return context.attachments.download(attachment_id)
+
+    return download
+
+
+async def _render(
+    item: ConversationMessage, context: AgentContext | None, on_attachment: AttachmentHandler | None
+) -> Message | None:
+    texts: list[str] = []
+    images: list[Image] = []
+    files: list[File] = []
+    if item.message.subject:
+        texts.append(f"Subject: {item.message.subject}")
+    if item.message.text:
+        texts.append(item.message.text)
+    handler = on_attachment or convert_attachment
+    for attachment in item.message.attachments:
+        conversion = AttachmentConversion(
+            message=item, attachment=attachment, download=_downloader(context, attachment.id)
+        )
+        result = await _call(handler, conversion)
+        for part in result if isinstance(result, list) else [result]:
+            if isinstance(part, str):
+                texts.append(part)
+            elif isinstance(part, Image):
+                images.append(part)
+            elif isinstance(part, File):
+                files.append(part)
+    if not texts and not images and not files:
+        return None
+    if not texts:
+        # Providers reject empty text beside media; name the files instead of sending "".
+        texts.append("Attached: " + ", ".join(a.filename for a in item.message.attachments))
+    return Message(
+        id=item.id,
+        role=item.role,
+        content="\n\n".join(texts),
+        images=images or None,
+        files=files or None,
+    )

trytilde_agno-3.0.1/src/tilde_agno/tools.py

@@ -0,0 +1,221 @@
+"""Expose Tilde channel tools to Agno with provider schemas and audited tool-call ids intact, and
+publish the agent's own Agno tools to Tilde as bundled tools."""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import inspect
+import uuid
+from collections.abc import Callable, Mapping, Sequence
+from contextvars import ContextVar
+from typing import Any
+
+from agno.tools.function import Function, FunctionCall
+from agno.tools.toolkit import Toolkit
+
+from tilde import AgentContext, BundledOptions, ChannelTool, Tool, ToolAnnotations
+from tilde._tools import ToolSpec, bundled_tool, model_tool_name, tool_spec
+
+# The FunctionCall of the Tilde tool being executed; a routed tools.execute runs within it.
+_FUNCTION_CALL: ContextVar[FunctionCall] = ContextVar("tilde_agno_function_call")
+
+
+def convert_to_agno_tools(
+    channels: Mapping[str, ChannelTool | Tool],
+    *,
+    instructions: Mapping[str, str] | None = None,
+    prefix: str = "",
+) -> list[Function]:
+    """Build Agno ``Function`` tools that keep provider schemas and execution ids.
+
+    ``skip_entrypoint_processing`` stops Agno from replacing the provider JSON schema with one
+    introspected from the entrypoint. Agno injects the running ``FunctionCall`` into an
+    entrypoint parameter named ``fc``; its ``call_id`` is the model's tool-call id and is
+    forwarded to Tilde's audited execution. A provider schema with a property named ``fc`` is
+    rejected here because Agno would drop that argument before it reached the channel.
+    ``instructions`` overrides descriptions by channel name; ``prefix`` namespaces model tool
+    names when combining collections.
+    """
+    result: list[Function] = []
+    names: set[str] = set()
+    for name, channel in channels.items():
+        key = model_tool_name(f"{prefix}{name}")
+        if not key or key in names:
+            raise ValueError("Conflicting or invalid model tool names")
+        names.add(key)
+        if "fc" in (channel.input_schema.get("properties") or {}):
+            raise ValueError(
+                f"{name}: Agno reserves the `fc` argument for its injected FunctionCall"
+            )
+        description = (
+            instructions[name]
+            if instructions is not None and name in instructions
+            else channel.description
+        )
+        result.append(
+            Function(
+                name=key,
+                description=description,
+                parameters=copy.deepcopy(channel.input_schema),
+                entrypoint=_entrypoint(channel),
+                skip_entrypoint_processing=True,
+            )
+        )
+    return result
+
+
+def _entrypoint(channel: ChannelTool | Tool):
+    async def execute(fc: FunctionCall, **arguments: Any) -> Any:
+        token = _FUNCTION_CALL.set(fc)
+        try:
+            return await channel.execute(arguments, tool_call_id=fc.call_id or None)
+        finally:
+            _FUNCTION_CALL.reset(token)
+
+    return execute
+
+
+async def with_tilde_tools(
+    ctx: AgentContext,
+    native_tools: Sequence[Callable[..., Any] | Function | Toolkit],
+    *,
+    options: Mapping[str, BundledOptions] | None = None,
+) -> list[Function]:
+    """The current channel's tools, the agent's other Tilde tools and its own tools, as Agno
+    ``Function``s for ``Agent(tools=...)``.
+
+    ``native_tools`` are plain functions, ``@tool`` functions or toolkits (expanded to their
+    functions). Each is published to Tilde with its name, description, parameter schema and MCP
+    ``annotations`` hints, so ``tools.search`` finds it and a ``tools.execute`` naming it runs it
+    here, and is returned as a copy whose calls are audited once with the model's call id by
+    ``pre_hook``/``post_hook`` chained around the tool's own hooks. Agno has no free metadata,
+    so the summary and display come from ``options[name]``. Call it once per invocation.
+
+    Caveats: run the agent with ``arun``; the audit hooks are async, and Agno's sync path does
+    not await them. Agno logs and swallows hook exceptions, so a failed audit never fails the
+    call. Toolkit-level instructions are not carried over. Agno has no output schema.
+    """
+    functions = convert_to_agno_tools({**ctx.channel.current, **ctx.agent_tools})
+    names = {function.name for function in functions}
+    definitions = {}
+    for native in functions_of(native_tools):
+        if native.name in names:
+            raise ValueError(f"Tool {native.name} conflicts with another tool")
+        names.add(native.name)
+        function = _audited(ctx, native)
+        definitions[function.name] = bundled_tool(
+            describe_tool(function, options), _route(function)
+        )
+        functions.append(function)
+    # Published even when empty, so tools removed since the last call stop running here.
+    await ctx._set_bundled_tools(definitions)
+    return functions
+
+
+def describe_tool(
+    function: Function, options: Mapping[str, BundledOptions] | None = None
+) -> ToolSpec:
+    """What ``with_tilde_tools`` publishes and ``tilde deploy`` declares for one tool, from a
+    ``Function`` whose entrypoint has been processed (see ``processed``)."""
+    hints = function.annotations or {}
+    annotations = (
+        ToolAnnotations(
+            read_only=bool(hints.get("readOnlyHint")),
+            destructive=bool(hints.get("destructiveHint")),
+            idempotent=bool(hints.get("idempotentHint")),
+            open_world=bool(hints.get("openWorldHint")),
+        )
+        if hints
+        else None
+    )
+    return tool_spec(
+        function.name,
+        function.description or "",
+        function.parameters,
+        annotations=annotations,
+        options=(options or {}).get(function.name),
+    )
+
+
+def processed(native: Function) -> Function:
+    """A copy with the parameters and description Agno introspects from the entrypoint."""
+    function = native.model_copy(deep=True)
+    function.process_entrypoint()
+    return function
+
+
+def functions_of(tools: Sequence[Callable[..., Any] | Function | Toolkit]) -> list[Function]:
+    """Plain functions, ``@tool`` functions and toolkits (expanded) as unprocessed ``Function``s."""
+    result: list[Function] = []
+    for tool in tools:
+        if isinstance(tool, Toolkit):
+            result.extend(tool.get_async_functions().values())
+        elif isinstance(tool, Function):
+            result.append(tool)
+        else:
+            result.append(Function.from_callable(tool))
+    return result
+
+
+def _audited(ctx: AgentContext, native: Function) -> Function:
+    # The entrypoint stays untouched so Agno still injects agent, run_context and media.
+    function = processed(native)
+    pre, post = native.pre_hook, native.post_hook
+
+    async def pre_hook(fc: FunctionCall) -> None:
+        fc.call_id = fc.call_id or str(uuid.uuid4())
+        await ctx._report_bundled(function.name, fc.call_id, "running", input=fc.arguments)
+        if pre is not None:
+            await _call_hook(pre, fc)
+
+    async def post_hook(fc: FunctionCall) -> None:
+        # Agno runs the post hook in a finally block: an error means the call failed, and a
+        # cancelled call is left unreported like any other cancellation.
+        call = fc.call_id or ""
+        task = asyncio.current_task()
+        if task is not None and task.cancelling():
+            pass
+        elif fc.error is not None:
+            await ctx._report_bundled(function.name, call, "failed", error=fc.error)
+        else:
+            await ctx._report_bundled(function.name, call, "completed", output=fc.result)
+        if post is not None:
+            await _call_hook(post, fc)
+
+    function.pre_hook = pre_hook
+    function.post_hook = post_hook
+    return function
+
+
+async def _call_hook(hook: Callable[..., Any], fc: FunctionCall) -> None:
+    # The developer's own hook, with the arguments Agno would have injected by name.
+    available = {
+        "agent": fc.function._agent,
+        "team": fc.function._team,
+        "run_context": fc.function._run_context,
+        "fc": fc,
+    }
+    parameters = inspect.signature(hook).parameters
+    result = hook(**{name: value for name, value in available.items() if name in parameters})
+    if inspect.isawaitable(result):
+        await result
+
+
+def _route(function: Function):
+    # A tools.execute naming this tool runs it as Agno would, with the agent and run context of
+    # the tools.execute call, audited once by its hooks.
+    async def execute(input: Any, call: str) -> Any:
+        outer = _FUNCTION_CALL.get(None)
+        inner = function.model_copy(deep=True)
+        if outer is not None:
+            inner._agent = outer.function._agent
+            inner._team = outer.function._team
+            inner._run_context = outer.function._run_context
+        fc = FunctionCall(function=inner, arguments=input, call_id=call)
+        result = await fc.aexecute()
+        if result.status == "failure":
+            raise RuntimeError(result.error or f"{function.name} failed")
+        return fc.result
+
+    return execute