trytilde-openai-agents 3.0.1__tar.gz

trytilde_openai_agents-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_openai_agents-3.0.1/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: trytilde-openai-agents
+Version: 3.0.1
+Summary: Tilde adapter for the OpenAI Agents SDK: typed history to Responses input items and channel tools to function tools
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: openai-agents<1,>=0.22
+Requires-Dist: trytilde
+Description-Content-Type: text/markdown
+
+# OpenAI Agents SDK adapter
+
+Core history and delivery live in `trytilde`. This package converts typed context to
+OpenAI Agents SDK input items and channel tools to `FunctionTool`s, bundles each invocation's
+run options (`tilde_openai_agents`) and lets `tilde deploy` discover module-level agents.
+
+```python
+import tilde
+from agents import Agent, OpenAIResponsesModel, Runner, set_tracing_disabled
+from openai import AsyncOpenAI
+from tilde_openai_agents import convert_to_openai_agents_messages, tilde_openai_agents
+
+set_tracing_disabled(True)  # or OPENAI_AGENTS_DISABLE_TRACING=1; keeps traces out of OpenAI
+INFERENCE = tilde.inference("default")
+client = AsyncOpenAI(
+    base_url=INFERENCE.base_url, api_key=INFERENCE.api_key, http_client=INFERENCE.async_client()
+)
+agent = Agent(
+    name="assistant",
+    instructions="Respond using the current channel's tools. Returned model text is private.",
+    model=OpenAIResponsesModel(model="gpt-4o-mini", openai_client=client),
+)
+
+
+async def run(ctx):
+    history = await ctx.message.history()
+    items = await convert_to_openai_agents_messages(history.items, context=ctx)
+    run_agent, run_config = await tilde_openai_agents(ctx, agent)
+    await Runner.run(run_agent, items, run_config=run_config, max_turns=8)
+```
+
+`tilde_openai_agents(ctx, agent, run_config=None)` returns a clone of `agent` and a
+`RunConfig` (a copy of yours, when given):
+
+- the clone has the current channel's tools;
+- skills assigned in the registry: with a local `ShellTool` they join its environment
+  `skills` (written to disk by `ctx.skills.directory()`); otherwise the clone gets the
+  `list_skills` / `read_skill` tools and `ctx.skills.summary()` after its instructions;
+- the config's `call_model_input_filter` (chained after yours) checks cancellation before
+  every model call, stamps the invocation's inference calls with the calling agent's dynamic
+  instructions and adds steering input as user messages. The SDK sends filtered input for
+  one call only, so steered messages are re-inserted where they arrived on later calls; with
+  server-managed conversations (`previous_response_id`, `conversation_id`) that duplicates
+  them.
+
+Handoff targets and agent tools run as defined; only the returned agent has channel tools.
+
+## Deploy discovery
+
+`tilde deploy` (entry point `tilde.discover`) registers every module-level `Agent` and the
+agents reachable through its handoffs and `as_tool` tools (cycles are fine):
+`<name>/instructions` (a string is plain, a function dynamic with its source) and
+`<name>/handoff_description`. Skill folders the SDK loads from disk are shipped: local
+`ShellTool` environment skills and a `SandboxAgent`'s `Skills(from_=LocalDir(...))` or
+`lazy_from=LocalDirLazySkillSource(...)`, resolved from the working directory. Hosted
+prompts (`prompt={"id": ...}`) are versioned by OpenAI and reported as warnings. Handoff
+targets and agent-tool agents are read from private fields (openai-agents 0.22); an
+unreadable one is reported.
+
+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 (`output_text` parts); everything else is a user item (`input_text`).
+
+Returned items never carry an `id`: the Responses API rejects ids it did not issue. The
+Tilde message id is stored only inside the cached representation, where it validates that
+a cached rendering belongs to the message being hydrated.
+
+Images and PDFs are downloaded through `ctx.attachments.download` and embedded as
+`input_image` / `input_file` data URLs. 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. Without a context
+or custom handler, a message with attachments raises instead of being silently truncated.
+
+```python
+history = await ctx.message.history(include_work=True)
+items = await convert_to_openai_agents_messages(
+    history.items,
+    context=ctx,
+    on_message=MessageHandlers(
+        goal=lambda item: {
+            "role": "user",
+            "content": [{"type": "input_text", "text": f"Our goal: {item.goal.objective}"}],
+        },
+        task=lambda item: None,  # Omit this type, or provide a different rendering.
+    ),
+    on_attachment=decode_your_format,  # async def (AttachmentConversion) -> part | [parts] | 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 (incomplete
+conversation messages are skipped unless a `message` handler is given). Completed
+conversation conversions use the existing per-agent cache, in bounded batches (100 items or
+1 MiB). Files are hydrated afresh and are never stored as data URLs in the cache;
+objectives/goals/tasks remain live projections rather than cached chat records.
+
+## Channel tools
+
+`convert_to_openai_agents_tools(ctx.channel.current)` preserves the provider's descriptions
+and JSON schemas (`strict_json_schema=False`, so provider schemas are used unchanged) and
+forwards the Agents SDK tool-call id (`ToolContext.tool_call_id`) to Tilde's audited tool
+execution. Provider results are returned to the model as JSON strings. 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 collections, use
+`prefix="slack_"` (or another prefix) to keep model tool names distinct; names are sanitized
+to `[a-zA-Z0-9_-]`, truncated to 64 characters with a stable hash suffix, and conflicts raise.
+
+The core SDK exposes 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.
+`ctx.channel.current` never falls back to a different connection.
+
+## Bundled tools
+
+The agent's own function tools join Tilde's with one call:
+
+```python
+from agents import Agent, function_tool
+from tilde import BundledOptions
+from tilde_openai_agents import with_tilde_tools
+
+
+@function_tool
+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(name="assistant", tools=tools)
+```
+
+`with_tilde_tools` returns the current channel's tools, `ctx.agent_tools` and copies of the
+native `FunctionTool`s with an audited `on_invoke_tool`, and publishes the native tools to
+Tilde with their parameter and output schemas, so `tools.search` finds them and a
+`tools.execute` naming one runs it here with the run's context. Every call is audited once with
+the model's call id. `FunctionTool` has no free metadata, so summaries come from `options`.
+`@function_tool` turns an exception into an error string for the model by default, so such a
+failure is audited as completed with that text; `failure_error_function=None` audits it as
+failed (and fails the run).

trytilde_openai_agents-3.0.1/README.md

@@ -0,0 +1,148 @@
+# OpenAI Agents SDK adapter
+
+Core history and delivery live in `trytilde`. This package converts typed context to
+OpenAI Agents SDK input items and channel tools to `FunctionTool`s, bundles each invocation's
+run options (`tilde_openai_agents`) and lets `tilde deploy` discover module-level agents.
+
+```python
+import tilde
+from agents import Agent, OpenAIResponsesModel, Runner, set_tracing_disabled
+from openai import AsyncOpenAI
+from tilde_openai_agents import convert_to_openai_agents_messages, tilde_openai_agents
+
+set_tracing_disabled(True)  # or OPENAI_AGENTS_DISABLE_TRACING=1; keeps traces out of OpenAI
+INFERENCE = tilde.inference("default")
+client = AsyncOpenAI(
+    base_url=INFERENCE.base_url, api_key=INFERENCE.api_key, http_client=INFERENCE.async_client()
+)
+agent = Agent(
+    name="assistant",
+    instructions="Respond using the current channel's tools. Returned model text is private.",
+    model=OpenAIResponsesModel(model="gpt-4o-mini", openai_client=client),
+)
+
+
+async def run(ctx):
+    history = await ctx.message.history()
+    items = await convert_to_openai_agents_messages(history.items, context=ctx)
+    run_agent, run_config = await tilde_openai_agents(ctx, agent)
+    await Runner.run(run_agent, items, run_config=run_config, max_turns=8)
+```
+
+`tilde_openai_agents(ctx, agent, run_config=None)` returns a clone of `agent` and a
+`RunConfig` (a copy of yours, when given):
+
+- the clone has the current channel's tools;
+- skills assigned in the registry: with a local `ShellTool` they join its environment
+  `skills` (written to disk by `ctx.skills.directory()`); otherwise the clone gets the
+  `list_skills` / `read_skill` tools and `ctx.skills.summary()` after its instructions;
+- the config's `call_model_input_filter` (chained after yours) checks cancellation before
+  every model call, stamps the invocation's inference calls with the calling agent's dynamic
+  instructions and adds steering input as user messages. The SDK sends filtered input for
+  one call only, so steered messages are re-inserted where they arrived on later calls; with
+  server-managed conversations (`previous_response_id`, `conversation_id`) that duplicates
+  them.
+
+Handoff targets and agent tools run as defined; only the returned agent has channel tools.
+
+## Deploy discovery
+
+`tilde deploy` (entry point `tilde.discover`) registers every module-level `Agent` and the
+agents reachable through its handoffs and `as_tool` tools (cycles are fine):
+`<name>/instructions` (a string is plain, a function dynamic with its source) and
+`<name>/handoff_description`. Skill folders the SDK loads from disk are shipped: local
+`ShellTool` environment skills and a `SandboxAgent`'s `Skills(from_=LocalDir(...))` or
+`lazy_from=LocalDirLazySkillSource(...)`, resolved from the working directory. Hosted
+prompts (`prompt={"id": ...}`) are versioned by OpenAI and reported as warnings. Handoff
+targets and agent-tool agents are read from private fields (openai-agents 0.22); an
+unreadable one is reported.
+
+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 (`output_text` parts); everything else is a user item (`input_text`).
+
+Returned items never carry an `id`: the Responses API rejects ids it did not issue. The
+Tilde message id is stored only inside the cached representation, where it validates that
+a cached rendering belongs to the message being hydrated.
+
+Images and PDFs are downloaded through `ctx.attachments.download` and embedded as
+`input_image` / `input_file` data URLs. 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. Without a context
+or custom handler, a message with attachments raises instead of being silently truncated.
+
+```python
+history = await ctx.message.history(include_work=True)
+items = await convert_to_openai_agents_messages(
+    history.items,
+    context=ctx,
+    on_message=MessageHandlers(
+        goal=lambda item: {
+            "role": "user",
+            "content": [{"type": "input_text", "text": f"Our goal: {item.goal.objective}"}],
+        },
+        task=lambda item: None,  # Omit this type, or provide a different rendering.
+    ),
+    on_attachment=decode_your_format,  # async def (AttachmentConversion) -> part | [parts] | 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 (incomplete
+conversation messages are skipped unless a `message` handler is given). Completed
+conversation conversions use the existing per-agent cache, in bounded batches (100 items or
+1 MiB). Files are hydrated afresh and are never stored as data URLs in the cache;
+objectives/goals/tasks remain live projections rather than cached chat records.
+
+## Channel tools
+
+`convert_to_openai_agents_tools(ctx.channel.current)` preserves the provider's descriptions
+and JSON schemas (`strict_json_schema=False`, so provider schemas are used unchanged) and
+forwards the Agents SDK tool-call id (`ToolContext.tool_call_id`) to Tilde's audited tool
+execution. Provider results are returned to the model as JSON strings. 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 collections, use
+`prefix="slack_"` (or another prefix) to keep model tool names distinct; names are sanitized
+to `[a-zA-Z0-9_-]`, truncated to 64 characters with a stable hash suffix, and conflicts raise.
+
+The core SDK exposes 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.
+`ctx.channel.current` never falls back to a different connection.
+
+## Bundled tools
+
+The agent's own function tools join Tilde's with one call:
+
+```python
+from agents import Agent, function_tool
+from tilde import BundledOptions
+from tilde_openai_agents import with_tilde_tools
+
+
+@function_tool
+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(name="assistant", tools=tools)
+```
+
+`with_tilde_tools` returns the current channel's tools, `ctx.agent_tools` and copies of the
+native `FunctionTool`s with an audited `on_invoke_tool`, and publishes the native tools to
+Tilde with their parameter and output schemas, so `tools.search` finds them and a
+`tools.execute` naming one runs it here with the run's context. Every call is audited once with
+the model's call id. `FunctionTool` has no free metadata, so summaries come from `options`.
+`@function_tool` turns an exception into an error string for the model by default, so such a
+failure is audited as completed with that text; `failure_error_function=None` audits it as
+failed (and fails the run).

trytilde_openai_agents-3.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "trytilde-openai-agents"
+version = "3.0.1"
+description = "Tilde adapter for the OpenAI Agents SDK: typed history to Responses input items and channel tools to function tools"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+dependencies = ["trytilde", "openai-agents>=0.22,<1"]
+
+# `tilde deploy` reads module-level agents' instructions and skill folders through this.
+[project.entry-points."tilde.discover"]
+openai-agents = "tilde_openai_agents.discover:discover"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tilde_openai_agents"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/tilde_openai_agents", "README.md"]

trytilde_openai_agents-3.0.1/src/tilde_openai_agents/__init__.py

@@ -0,0 +1,29 @@
+"""Tilde adapter for the OpenAI Agents SDK (``openai-agents``).
+
+Core history and delivery live in ``trytilde``. This package converts typed context into
+Responses API input items, exposes channel tools as ``agents.FunctionTool`` instances, bundles
+the per-invocation run options (``tilde_openai_agents``) and lets ``tilde deploy`` discover
+module-level agents' prompts and skills.
+"""
+
+from tilde_openai_agents.attachments import (
+    AttachmentConversion,
+    AttachmentHandler,
+    convert_attachment,
+)
+from tilde_openai_agents.discover import discover
+from tilde_openai_agents.invocation import tilde_openai_agents
+from tilde_openai_agents.messages import MessageHandlers, convert_to_openai_agents_messages
+from tilde_openai_agents.tools import convert_to_openai_agents_tools, with_tilde_tools
+
+__all__ = [
+    "AttachmentConversion",
+    "AttachmentHandler",
+    "MessageHandlers",
+    "convert_attachment",
+    "convert_to_openai_agents_messages",
+    "convert_to_openai_agents_tools",
+    "discover",
+    "tilde_openai_agents",
+    "with_tilde_tools",
+]

trytilde_openai_agents-3.0.1/src/tilde_openai_agents/attachments.py

@@ -0,0 +1,86 @@
+"""Attachment hydration into Responses API content parts."""
+
+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
+
+# Responses API content parts: input_text, input_image, input_file (openai TypedDicts).
+ContentPart = dict[str, Any]
+Conversion = ContentPart | list[ContentPart] | None
+AttachmentHandler = Callable[["AttachmentConversion"], Conversion | Awaitable[Conversion]]
+
+_TEXT_TYPES = {"application/json", "application/xml"}
+_IMAGE_TYPES = {"image/jpeg", "image/png", "image/gif", "image/webp"}
+_FILE_TYPES = {"application/pdf"}
+
+
+@dataclass(slots=True)
+class AttachmentConversion:
+    message: ConversationMessage
+    attachment: Attachment
+    download: Callable[[], Awaitable[DownloadedAttachment]]
+    """Uses the current invocation's authenticated, thread-scoped attachment API."""
+
+
+async def convert_attachment(input: AttachmentConversion) -> ContentPart:
+    """Hydrate images as ``input_image``, PDFs as ``input_file`` and textual files as real text.
+
+    Assistant messages cannot carry image or file parts in the Responses API, so the agent's
+    own attachments are described instead of downloaded.
+    """
+    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
+    file = media_type in _FILE_TYPES
+    if input.message.role == "assistant" and not text:
+        return _text(f"Attached file: {attachment.filename} ({media_type}).")
+    if not (text or image or file):
+        return _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 _text(f"Attached file: {attachment.filename}\n{content}")
+    data_url = f"data:{media_type};base64,{base64.b64encode(result.content).decode('ascii')}"
+    if image:
+        return {"type": "input_image", "detail": "auto", "image_url": data_url}
+    return {"type": "input_file", "filename": attachment.filename, "file_data": data_url}
+
+
+def _text(text: str) -> ContentPart:
+    return {"type": "input_text", "text": text}
+
+
+_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",
+}
+
+
+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_openai_agents-3.0.1/src/tilde_openai_agents/discover.py

@@ -0,0 +1,205 @@
+"""``tilde deploy`` discovery for the OpenAI Agents SDK (entry point ``tilde.discover``).
+
+A module-level ``Agent`` contributes itself and every agent reachable through its handoffs and
+agent tools (``Agent.as_tool``), each once:
+
+- ``<name>/instructions``: a string is plain text; a function is dynamic with its source.
+- ``<name>/handoff_description``: plain text.
+- A hosted ``prompt`` (``{"id", "version"}``) lives in the OpenAI dashboard and is not versioned
+  by Tilde; it is reported as a warning.
+- Skill folders the SDK loads from disk: local ``ShellTool`` environment skills and a
+  ``SandboxAgent``'s ``Skills(from_=LocalDir(...))`` / ``lazy_from=LocalDirLazySkillSource``.
+  Relative paths resolve from the working directory, as the SDK resolves them.
+- ``FunctionTool``s in ``tools`` (agent tools included), declared as ``with_tilde_tools``
+  publishes them, as is a ``define_tools`` value of ``FunctionTool``s. Hosted and shell tools
+  are not.
+
+Handoff targets and agent-tool agents are only reachable through private fields
+(``Handoff._agent_ref``, ``FunctionTool._agent_instance``, openai-agents 0.22); an unreadable
+one is reported as a warning.
+"""
+
+from __future__ import annotations
+
+import inspect
+import re
+import sys
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+from agents import Agent, FunctionTool, Handoff, ShellTool
+from agents.sandbox import SandboxAgent
+from agents.sandbox.capabilities import LocalDirLazySkillSource, Skills
+from agents.sandbox.entries import LocalDir
+
+from tilde import BundledTools
+from tilde.discovery import (
+    PROMPT_FORMAT_DYNAMIC,
+    PROMPT_FORMAT_PLAIN,
+    Discovered,
+    DiscoveryContext,
+    declared_prompt,
+    declared_tool,
+)
+from tilde.prompts import canonical_json, prompt_hash
+from tilde.skills import read_skill, read_skills
+from tilde_openai_agents.tools import describe_tool
+
+_UNSAFE = re.compile(r"[^A-Za-z0-9._-]")
+
+
+def prompt_name(agent: Agent[Any], field: str) -> str:
+    """Prompt names allow ``[A-Za-z0-9._/-]``; agent names are free text."""
+    return f"{_UNSAFE.sub('-', agent.name)[:96] or 'agent'}/{field}"
+
+
+def reachable_agents(root: Agent[Any], warn: Any = None) -> Iterator[tuple[str, Agent[Any]]]:
+    """``root`` and every agent reachable through handoffs and agent tools, each once, with
+    the attribute path from ``root`` (``handoffs.billing``, ``tools.lookup``)."""
+    seen: set[int] = set()
+    pending: list[tuple[str, Agent[Any]]] = [("", root)]
+    while pending:
+        path, agent = pending.pop(0)
+        if id(agent) in seen:
+            continue
+        seen.add(id(agent))
+        yield path, agent
+        prefix = f"{path}." if path else ""
+        for item in agent.handoffs:
+            target = item
+            if isinstance(item, Handoff):
+                ref = getattr(item, "_agent_ref", None)
+                target = ref() if callable(ref) else None
+            if isinstance(target, Agent):
+                pending.append((f"{prefix}handoffs.{target.name}", target))
+            elif warn is not None:
+                warn(f"handoff {getattr(item, 'agent_name', '?')} of agent {agent.name}")
+        for tool in agent.tools:
+            if not getattr(tool, "_is_agent_tool", False):
+                continue
+            target = getattr(tool, "_agent_instance", None)
+            if isinstance(target, Agent):
+                pending.append((f"{prefix}tools.{tool.name}", target))
+            elif warn is not None:
+                warn(f"agent tool {tool.name} of agent {agent.name}")
+
+
+def dynamic_source(instructions: Any) -> str | None:
+    """The source of an instructions function (a callable object's class), or None when Python
+    cannot read it."""
+    for candidate in (instructions, type(instructions)):
+        try:
+            return inspect.getsource(candidate)
+        except (OSError, TypeError):
+            continue
+    return None
+
+
+def instructions_stamp(agent: Agent[Any]) -> tuple[str, str] | None:
+    """``(name, hash)`` of an agent's dynamic instructions, as ``tilde deploy`` registers them."""
+    if not callable(agent.instructions):
+        return None
+    source = dynamic_source(agent.instructions)
+    if source is None:
+        return None
+    return prompt_name(agent, "instructions"), prompt_hash(source, {}, canonical_json({}))
+
+
+def discover(value: Any, context: DiscoveryContext) -> Discovered | None:
+    if isinstance(value, BundledTools):
+        if not value.tools or not all(isinstance(tool, FunctionTool) for tool in value.tools):
+            return None
+        origin = f"{context.origin()}.tools"
+        return Discovered(
+            tools=[
+                declared_tool(describe_tool(tool, value.options), f"{origin}.{tool.name}")
+                for tool in value.tools
+            ]
+        )
+    if not isinstance(value, Agent):
+        return 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}"
+    found = Discovered()
+
+    def unreadable(what: str) -> None:
+        context.warn(f"{origin}: {what} could not be read; its prompts are not registered")
+
+    for path, agent in reachable_agents(value, unreadable):
+        at = f"{origin}.{path}" if path else origin
+        _prompts(agent, at, found, context)
+        _skills(agent, at, found, context)
+        found.tools += [
+            declared_tool(describe_tool(tool), f"{at}.tools.{tool.name}")
+            for tool in agent.tools
+            if isinstance(tool, FunctionTool)
+        ]
+    return found
+
+
+def _prompts(agent: Agent[Any], at: str, found: Discovered, context: DiscoveryContext) -> None:
+    instructions = agent.instructions
+    if isinstance(instructions, str) and instructions:
+        found.prompts.append(
+            declared_prompt(
+                prompt_name(agent, "instructions"),
+                instructions,
+                PROMPT_FORMAT_PLAIN,
+                f"{at}.instructions",
+            )
+        )
+    elif callable(instructions):
+        source = dynamic_source(instructions)
+        if source is None:
+            context.warn(f"{at}.instructions: the function's source cannot be read")
+        else:
+            found.prompts.append(
+                declared_prompt(
+                    prompt_name(agent, "instructions"),
+                    source,
+                    PROMPT_FORMAT_DYNAMIC,
+                    f"{at}.instructions",
+                )
+            )
+    if agent.handoff_description:
+        found.prompts.append(
+            declared_prompt(
+                prompt_name(agent, "handoff_description"),
+                agent.handoff_description,
+                PROMPT_FORMAT_PLAIN,
+                f"{at}.handoff_description",
+            )
+        )
+    if agent.prompt is not None:
+        hosted = agent.prompt.get("id") if isinstance(agent.prompt, dict) else "(dynamic)"
+        context.warn(
+            f"{at}.prompt: OpenAI-hosted prompt {hosted} is versioned by OpenAI, not by Tilde"
+        )
+
+
+def _skills(agent: Agent[Any], at: str, found: Discovered, context: DiscoveryContext) -> None:
+    for tool in agent.tools:
+        if not isinstance(tool, ShellTool) or not isinstance(tool.environment, dict):
+            continue
+        if tool.environment.get("type") != "local":
+            continue
+        for skill in tool.environment.get("skills") or []:
+            directory = context.root / skill["path"]
+            if (directory / "SKILL.md").is_file():
+                found.skills.append(read_skill(directory))
+            else:
+                context.warn(f"{at}.tools.{tool.name}: skill {skill['name']} has no SKILL.md")
+    if not isinstance(agent, SandboxAgent):
+        return
+    for capability in agent.capabilities:
+        if not isinstance(capability, Skills):
+            continue
+        source = capability.from_
+        if isinstance(capability.lazy_from, LocalDirLazySkillSource):
+            source = capability.lazy_from.source
+        if isinstance(source, LocalDir) and source.src is not None:
+            found.skills.extend(read_skills(context.root / source.src))
+        else:
+            context.warn(f"{at}.capabilities: only LocalDir skills are registered")

trytilde_openai_agents-3.0.1/src/tilde_openai_agents/invocation.py

@@ -0,0 +1,144 @@
+"""The per-invocation pieces of an OpenAI Agents SDK run.
+
+``Runner.run`` takes the agent positionally and everything else as options, so the helper
+returns both: a clone of the module-level agent carrying this invocation's tools and skills,
+and a ``RunConfig`` whose ``call_model_input_filter`` runs before every model call.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import inspect
+from pathlib import Path
+from typing import Any
+
+from agents import Agent, RunConfig, RunContextWrapper, ShellTool, TResponseInputItem
+from agents.run_config import CallModelData, CallModelInputFilter, ModelInputData
+
+from tilde import AgentContext, BundledTools
+from tilde_openai_agents.discover import instructions_stamp, reachable_agents
+from tilde_openai_agents.tools import convert_to_openai_agents_tools, with_tilde_tools
+
+
+async def tilde_openai_agents(
+    ctx: AgentContext,
+    agent: Agent[Any],
+    *,
+    bundled: BundledTools | None = None,
+    run_config: RunConfig | None = None,
+) -> tuple[Agent[Any], RunConfig]:
+    """``agent, config = await tilde_openai_agents(ctx, agent, bundled=TOOLS)`` then
+    ``await Runner.run(agent, input, run_config=config, max_turns=8)``.
+
+    - 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)
+      are added to the returned clone of ``agent``.
+    - Skills assigned in the registry: with a local ``ShellTool`` they are added to its
+      environment ``skills`` (written to disk by ``ctx.skills.directory()``); otherwise the
+      ``list_skills``/``read_skill`` tools are added and ``ctx.skills.summary()`` is appended
+      to the instructions.
+    - Before every model call: cancellation is checked, the calling agent's dynamic
+      instructions stamp this invocation's inference calls, and steering input sent while the
+      agent works becomes user messages. ``run_config``'s own filter, if any, runs first.
+
+    Handoff targets and agent tools run as defined; only ``agent`` gets Tilde's tools.
+    """
+    stamps = {
+        candidate.name: stamp
+        for _, candidate in reachable_agents(agent)
+        if (stamp := instructions_stamp(candidate)) is not None
+    }
+    own = await with_tilde_tools(
+        ctx,
+        bundled.tools if bundled else [],
+        options=bundled.options if bundled else None,
+    )
+    tools = [*agent.tools, *own]
+    instructions = agent.instructions
+    shell = next(
+        (
+            tool
+            for tool in tools
+            if isinstance(tool, ShellTool) and (tool.environment or {}).get("type") == "local"
+        ),
+        None,
+    )
+    if shell is not None:
+        environment: dict[str, Any] = dict(shell.environment or {})
+        environment["skills"] = [*environment.get("skills", []), *await _local_skills(ctx)]
+        tools[tools.index(shell)] = dataclasses.replace(shell, environment=environment)
+    else:
+        summary = await ctx.skills.summary()
+        if summary:
+            tools.extend(convert_to_openai_agents_tools(ctx.skills.tools()))
+            instructions = _with_summary(instructions, summary)
+    config = dataclasses.replace(run_config) if run_config is not None else RunConfig()
+    config.call_model_input_filter = _input_filter(ctx, stamps, config.call_model_input_filter)
+    return agent.clone(tools=tools, instructions=instructions), config
+
+
+async def _local_skills(ctx: AgentContext) -> list[dict[str, str]]:
+    registry = [skill for skill in await ctx.skills.list() if not skill.deployed]
+    if not registry:
+        return []
+    root = Path(await ctx.skills.directory())
+    names = [skill.name for skill in registry]
+    skills = []
+    for skill in registry:
+        # `directory()` names a folder `<source>-<name>` only when two sources share a name.
+        folder = f"{skill.source}-{skill.name}" if names.count(skill.name) > 1 else skill.name
+        skills.append(
+            {"name": skill.name, "description": skill.description, "path": str(root / folder)}
+        )
+    return skills
+
+
+def _with_summary(instructions: Any, summary: str) -> Any:
+    if instructions is None:
+        return summary
+    if isinstance(instructions, str):
+        return f"{instructions}\n\n{summary}"
+
+    # The SDK requires exactly (context, agent).
+    async def with_summary(context: RunContextWrapper[Any], agent: Agent[Any]) -> str:
+        text = instructions(context, agent)
+        if inspect.isawaitable(text):
+            text = await text
+        return f"{text}\n\n{summary}"
+
+    return with_summary
+
+
+def _input_filter(
+    ctx: AgentContext,
+    stamps: dict[str, tuple[str, str]],
+    previous: CallModelInputFilter | None,
+) -> CallModelInputFilter:
+    # The SDK sends the filtered input for one call only and keeps its own history, so steered
+    # messages are remembered with their position and re-inserted on every later call. That
+    # assumes the SDK resends the history; with server-managed conversations
+    # (`previous_response_id`, `conversation_id`) it sends only new items.
+    steered: list[tuple[int, list[TResponseInputItem]]] = []
+
+    async def filter(data: CallModelData[Any]) -> ModelInputData:
+        if previous is not None:
+            updated = previous(data)
+            data.model_data = await updated if inspect.isawaitable(updated) else updated
+        ctx.check()
+        stamp = stamps.get(data.agent.name)
+        if stamp is not None:
+            ctx.activate_prompt(*stamp)
+        items = list(data.model_data.input)
+        inputs = ctx.take_inputs()
+        if inputs:
+            steered.append(
+                (len(items), [{"role": "user", "content": input.text} for input in inputs])
+            )
+        offset = 0
+        for position, added in steered:
+            at = min(position + offset, len(items))
+            items[at:at] = added
+            offset += len(added)
+        return ModelInputData(input=items, instructions=data.model_data.instructions)
+
+    return filter

trytilde_openai_agents-3.0.1/src/tilde_openai_agents/messages.py

@@ -0,0 +1,189 @@
+"""Typed Tilde context to Responses API input items for ``agents.Runner.run``."""
+
+from __future__ import annotations
+
+import inspect
+import json
+from collections.abc import Awaitable, Callable, Iterable
+from dataclasses import dataclass
+from typing import Any
+
+from agents import TResponseInputItem
+
+from tilde import (
+    AgentContext,
+    ContextMessage,
+    ConversationMessage,
+    GoalMessage,
+    ObjectiveMessage,
+    TaskMessage,
+)
+from tilde_openai_agents.attachments import (
+    AttachmentConversion,
+    AttachmentHandler,
+    convert_attachment,
+)
+
+Converted = TResponseInputItem | None
+Handler = Callable[[Any], Converted | Awaitable[Converted]]
+
+_MAX_ENTRY_BYTES = 1024 * 1024
+_MAX_BATCH_ITEMS = 100
+_CACHED_PART_TYPES = {"input_text", "output_text"}
+
+
+@dataclass(slots=True)
+class MessageHandlers:
+    """Explicit handlers take precedence over cached and default conversion; 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
+
+
+async def convert_to_openai_agents_messages(
+    messages: Iterable[ContextMessage],
+    *,
+    context: AgentContext | None = None,
+    on_message: MessageHandlers | None = None,
+    on_attachment: AttachmentHandler | None = None,
+) -> list[TResponseInputItem]:
+    """Convert typed SDK context into Responses input items.
+
+    Returned items carry no ``id``: the Responses API rejects ids it did not issue. The Tilde
+    message id lives only in the cached representation, where it validates a hydration.
+    """
+    handlers = on_message or MessageHandlers()
+    output: list[TResponseInputItem] = []
+    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:
+        hydrated = False
+        if isinstance(item, ObjectiveMessage):
+            converted = await _convert(handlers.objective, item, "user", item.objective)
+        elif isinstance(item, GoalMessage):
+            converted = await _convert(
+                handlers.goal, item, "user", f"Goal ({item.goal.status}): {item.goal.objective}"
+            )
+        elif isinstance(item, TaskMessage):
+            text = f"Task ({item.task.status}): {item.task.title}"
+            if item.task.blocked_reason:
+                text += f"\nBlocked: {item.task.blocked_reason}"
+            converted = await _convert(handlers.task, item, "user", text)
+        elif handlers.message is not None:
+            converted = await _call(handlers.message, item)
+        elif item.message.status != "complete":
+            continue
+        else:
+            # File bytes are hydrated afresh through the scoped SDK, never replayed 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, complete, attachment-free messages are cached; work state stays live.
+        if (
+            context is None
+            or hydrated
+            or not isinstance(item, ConversationMessage)
+            or item.message.status != "complete"
+            or item.message.attachments
+        ):
+            continue
+        entry = {"id": item.id, **converted}
+        size = len(json.dumps(entry).encode())
+        if size > _MAX_ENTRY_BYTES:
+            continue
+        if len(batch) == _MAX_BATCH_ITEMS or batch_bytes + size > _MAX_ENTRY_BYTES:
+            await flush()
+        batch.append((item.id, json.loads(json.dumps(entry))))
+        batch_bytes += size
+    await flush()
+    return output
+
+
+async def _convert(
+    handler: Handler | None, item: ContextMessage, role: str, text: str
+) -> Converted:
+    """A supplied handler decides (None omits); otherwise render the default text item."""
+    return await _call(handler, item) if handler is not None else _text_item(role, text)
+
+
+async def _call(handler: Handler, item: ContextMessage) -> Converted:
+    result = handler(item)
+    if inspect.isawaitable(result):
+        result = await result
+    return result
+
+
+def _text_item(role: str, text: str) -> TResponseInputItem:
+    part_type = "output_text" if role == "assistant" else "input_text"
+    return {"role": role, "content": [{"type": part_type, "text": text}]}  # type: ignore[return-value]
+
+
+async def _render(
+    item: ConversationMessage, context: AgentContext | None, on_attachment: AttachmentHandler | None
+) -> Converted:
+    parts: list[dict[str, Any]] = []
+    if item.message.HasField("subject") and item.message.subject:
+        parts.append({"type": "input_text", "text": f"Subject: {item.message.subject}"})
+    if item.message.text:
+        parts.append({"type": "input_text", "text": item.message.text})
+    for attachment in item.message.attachments:
+
+        async def download(attachment_id: str = attachment.id):
+            if context is None:
+                raise RuntimeError(
+                    "Attachment conversion requires context or a custom on_attachment handler"
+                )
+            return await context.attachments.download(attachment_id)
+
+        converted = (on_attachment or convert_attachment)(
+            AttachmentConversion(message=item, attachment=attachment, download=download)
+        )
+        if inspect.isawaitable(converted):
+            converted = await converted
+        if converted is None:
+            continue
+        parts.extend(converted if isinstance(converted, list) else [converted])
+    if not parts:
+        return None
+    if item.role == "assistant":
+        parts = [
+            {**part, "type": "output_text"} if part.get("type") == "input_text" else part
+            for part in parts
+        ]
+    return {"role": item.role, "content": parts}  # type: ignore[return-value]
+
+
+def _hydrate(item: ConversationMessage) -> Converted:
+    """Reuse a cached rendering only when its id, role and text-only content check out."""
+    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 not isinstance(content, list) or not content:
+        return None
+    for part in content:
+        if (
+            not isinstance(part, dict)
+            or part.get("type") not in _CACHED_PART_TYPES
+            or not isinstance(part.get("text"), str)
+        ):
+            return None
+    return {"role": item.role, "content": content}  # type: ignore[return-value]

trytilde_openai_agents-3.0.1/src/tilde_openai_agents/tools.py

@@ -0,0 +1,150 @@
+"""Channel tools as ``agents.FunctionTool`` instances with audited, id-preserving execution, and
+the agent's own function tools published to Tilde as bundled tools."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from contextvars import ContextVar
+from dataclasses import replace
+from typing import Any
+
+from agents import FunctionTool
+from agents.tool_context import ToolContext
+
+from tilde import AgentContext, BundledOptions, ChannelTool, Tool
+from tilde._tools import ToolSpec, bundled_tool, model_tool_name, tool_spec
+
+# The ToolContext of the Tilde tool being executed; a routed tools.execute runs within it.
+_TOOL_CONTEXT: ContextVar[ToolContext[Any]] = ContextVar("tilde_openai_agents_tool_context")
+
+
+def convert_to_openai_agents_tools(
+    channels: Mapping[str, ChannelTool | Tool],
+    *,
+    instructions: Mapping[str, str] | None = None,
+    prefix: str = "",
+) -> list[FunctionTool]:
+    """Preserve provider descriptions and schemas; forward the model's call id to Tilde.
+
+    ``instructions`` overrides descriptions by channel tool name without touching schemas or
+    authorization. ``prefix`` namespaces model tool names when combining collections.
+    ``ctx.skills.tools()`` converts the same way.
+    """
+    tools: list[FunctionTool] = []
+    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)
+        description = (
+            instructions[name] if instructions and name in instructions else channel.description
+        )
+        tools.append(
+            FunctionTool(
+                name=key,
+                description=description,
+                params_json_schema=channel.input_schema,
+                on_invoke_tool=_invoker(channel),
+                strict_json_schema=False,
+            )
+        )
+    return tools
+
+
+def _invoker(channel: ChannelTool | Tool):
+    async def on_invoke_tool(ctx: ToolContext, input_json: str) -> str:
+        arguments = json.loads(input_json) if input_json.strip() else {}
+        token = _TOOL_CONTEXT.set(ctx)
+        try:
+            result = await channel.execute(arguments, tool_call_id=ctx.tool_call_id)
+        finally:
+            _TOOL_CONTEXT.reset(token)
+        return json.dumps(result, default=str)
+
+    return on_invoke_tool
+
+
+async def with_tilde_tools(
+    ctx: AgentContext,
+    native_tools: Sequence[FunctionTool],
+    *,
+    options: Mapping[str, BundledOptions] | None = None,
+) -> list[FunctionTool]:
+    """The current channel's tools, the agent's other Tilde tools and its own function tools,
+    for ``Agent(tools=...)``.
+
+    Each native tool (``@function_tool`` or ``FunctionTool``) is published to Tilde with its
+    name, description, parameter and output schemas, 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. ``FunctionTool`` has no free metadata, so the summary and
+    display come from ``options[name]``. Call it once per invocation.
+
+    Caveat: ``@function_tool`` turns a raised exception into an error string for the model by
+    default (``failure_error_function``), so such a failure is audited as completed with that
+    text; pass ``failure_error_function=None`` to have it audited as failed (it then fails the
+    run).
+    """
+    tools = convert_to_openai_agents_tools({**ctx.channel.current, **ctx.agent_tools})
+    names = {tool.name for tool in tools}
+    definitions = {}
+    for tool in native_tools:
+        if tool.name in names:
+            raise ValueError(f"Tool {tool.name} conflicts with another tool")
+        names.add(tool.name)
+        audited = replace(tool, on_invoke_tool=_audited(ctx, tool.name, tool.on_invoke_tool))
+        definitions[tool.name] = bundled_tool(describe_tool(tool, options), _route(audited))
+        tools.append(audited)
+    # 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: FunctionTool, 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,
+        tool.params_json_schema,
+        output_schema=tool.output_json_schema,
+        options=(options or {}).get(tool.name),
+    )
+
+
+def _audited(
+    ctx: AgentContext, name: str, invoke: Callable[[ToolContext[Any], str], Awaitable[Any]]
+):
+    async def on_invoke_tool(tool_ctx: ToolContext[Any], input_json: str) -> Any:
+        arguments = json.loads(input_json) if input_json.strip() else {}
+        return await ctx._run_audited(
+            name, tool_ctx.tool_call_id, arguments, lambda: invoke(tool_ctx, input_json)
+        )
+
+    return on_invoke_tool
+
+
+def _route(tool: FunctionTool):
+    # A tools.execute naming this tool runs it as the Agents SDK would, with the run context,
+    # usage and agent of the tools.execute call, audited once by its on_invoke_tool.
+    async def execute(input: Any, call: str) -> Any:
+        outer = _TOOL_CONTEXT.get(None)
+        arguments = json.dumps(input)
+        tool_ctx = (
+            ToolContext(
+                outer.context,
+                outer.usage,
+                tool_name=tool.name,
+                tool_call_id=call,
+                tool_arguments=arguments,
+                agent=outer.agent,
+                run_config=outer.run_config,
+            )
+            if outer is not None
+            else ToolContext(None, tool_name=tool.name, tool_call_id=call, tool_arguments=arguments)
+        )
+        return await tool.on_invoke_tool(tool_ctx, arguments)
+
+    return execute