cmpnd 0.27.2__tar.gz → 0.27.4__tar.gz

{cmpnd-0.27.2 → cmpnd-0.27.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.27.2
+Version: 0.27.4
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>

{cmpnd-0.27.2 → cmpnd-0.27.4}/cmpnd/__init__.py

@@ -214,3 +214,8 @@ def de_instrument() -> None:
     _gepa_patch.unpatch_gepa()
     _program_patch.unpatch_program_state()
     _rlm_patch.unpatch_rlm_tools()
+
+
+def _mcp_tool(declaration):  # pyright: ignore[reportUnusedFunction] -- generated bundles call this hook
+    """Keep generated declarations importable outside a worker without granting access."""
+    return declaration

{cmpnd-0.27.2 → cmpnd-0.27.4}/cmpnd/_authored_import.py

@@ -122,7 +122,6 @@ def _program_facts(
     from .authored import ProgramFacts
 
     references = deployment._mcp_tool_references(program)
-    deployment._refuse_mcp_tools_outside_rlm(program, references)
     pinned: dict[tuple[str, str], Any] = {}
     if references:
         import httpx

cmpnd-0.27.4/cmpnd/_runtime_tools.py

@@ -0,0 +1,39 @@
+"""Private provenance for tools that CMPND adds while a program runs."""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+_RUNTIME_TOOL_MARKER = "_cmpnd_runtime_tool"
+
+
+class _RuntimeToolProvenance:
+    """An in-process token that keeps its identity through DSPy module copies."""
+
+    def __copy__(self) -> _RuntimeToolProvenance:
+        return self
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> _RuntimeToolProvenance:
+        del memo
+        return self
+
+
+_RUNTIME_TOOL_PROVENANCE = _RuntimeToolProvenance()
+_T = TypeVar("_T")
+
+
+def mark_runtime_tool(tool: _T) -> _T:
+    """Mark a platform-created tool without trusting a caller-chosen boolean."""
+    setattr(tool, _RUNTIME_TOOL_MARKER, _RUNTIME_TOOL_PROVENANCE)
+    function = getattr(tool, "func", None)
+    if function is not None:
+        setattr(function, _RUNTIME_TOOL_MARKER, _RUNTIME_TOOL_PROVENANCE)
+    return tool
+
+
+def is_runtime_tool(tool: object) -> bool:
+    """Return whether this process marked the tool or its wrapped callable."""
+    if getattr(tool, _RUNTIME_TOOL_MARKER, None) is _RUNTIME_TOOL_PROVENANCE:
+        return True
+    function = getattr(tool, "func", None)
+    return getattr(function, _RUNTIME_TOOL_MARKER, None) is _RUNTIME_TOOL_PROVENANCE

{cmpnd-0.27.2 → cmpnd-0.27.4}/cmpnd/deployment.py

@@ -250,7 +250,7 @@ def _mcp_tool_references(module) -> list[Any]:
     """Every MCP reference the program's tools carry, deduplicated, in a stable order."""
     references: list[Any] = []
     seen: set[tuple[str, str]] = set()
-    for tool in packaging.module_tools(module).values():
+    for tool in packaging.declared_module_tools(module).values():
         reference = mcp_servers.mcp_tool_reference(tool)
         if reference is None:
             continue
@@ -262,48 +262,6 @@ def _mcp_tool_references(module) -> list[Any]:
     return references
 
 
-def _refuse_mcp_tools_outside_rlm(module, references: list[Any]) -> None:
-    """Refuse a program that declares MCP tools and is not a `dspy.RLM`.
-
-    **At deploy, because the alternative arrives mid-turn in a deployed program.** The
-    worker answers an MCP-backed tool where `dspy.RLM`'s inner interpreter parks waiting
-    for one; that is the only place it can intervene without the kernel holding a token it
-    must never see. A `dspy.ReAct` program calls its tools from kernel Python directly, so
-    the call reaches the `def` the packager generated and raises — loud, but at run time,
-    in front of whoever is reading the answer rather than whoever can change the program.
-
-    **A state check and not a name check.** `isinstance` against the live class is what
-    makes a subclass, a rename and a re-export all answer correctly; matching
-    `type(module).__name__` against a list would pass the first and refuse the last. It is
-    the reason this lives here and not in serve: the create body's `module_class` is a
-    display string a client fills in, and a guard over it would fail open in both
-    directions.
-
-    Absent `dspy.RLM` refuses too, following `cmpnd.callback`'s idiom. A dspy with no RLM
-    is a dspy with no path that can serve these tools at all, so refusing is the honest
-    answer rather than a gap.
-    """
-    if not references:
-        return
-    # Deferred, as every other dspy use in this module is: a deploy of a program with no
-    # MCP tools returns above and never pays for the import.
-    import dspy
-
-    if isinstance(module, getattr(dspy, "RLM", type(None))):
-        return
-    names = ", ".join(sorted(reference.tool_name for reference in references))
-    noun = "the MCP tool" if len(references) == 1 else "the MCP tools"
-    raise ValueError(
-        f"{type(module).__name__} declares {noun} {names}, and only dspy.RLM can call "
-        "them once deployed. The platform answers an MCP tool call underneath the sandbox, "
-        "at the point where RLM's interpreter waits for a tool result, and no other module "
-        "reaches that point — its tool call runs inside the sandbox, where the call would "
-        f"reach a stub and raise. Either wrap this program's work in dspy.RLM, or give "
-        f"{type(module).__name__} ordinary Python tools, which deploy as source and run in "
-        "the sandbox."
-    )
-
-
 def _server_identity(url: str) -> str:
     """A tool server's URL in the one form two spellings of it compare equal in.
 
@@ -381,7 +339,7 @@ def _resolve_mcp_tool_references(client: httpx.Client, config, references: list[
             server_url=reference.server_url,
             tool_name=reference.tool_name,
             schema_hash=str(tool.get("schema_hash") or ""),
-            input_schema=tool.get("input_schema") or {},
+            input_schema=mcp_servers.registry_schema(tool),
             description=str(tool.get("description") or ""),
         )
     return pinned
@@ -424,10 +382,8 @@ def deploy(module, metric=None, timeout=300, metadata=None):
     # Resolve the program's MCP tool references against the org's registry, before
     # anything is packaged and before a deployment row exists. A program with no MCP
     # tools asks the registry nothing.
+    # Validate declarations before contacting the registry or creating a deployment.
     references = _mcp_tool_references(module)
-    # Before the round trip, because it needs nothing from the registry: a module that
-    # cannot call these tools at all is refused whatever the registry says about them.
-    _refuse_mcp_tools_outside_rlm(module, references)
     pinned_mcp_tools: dict[tuple[str, str], Any] = {}
     if references:
         with httpx.Client(timeout=httpx.Timeout(_TIMEOUT_SECONDS, connect=_CONNECT_TIMEOUT_SECONDS)) as client:

{cmpnd-0.27.2 → cmpnd-0.27.4}/cmpnd/ir/reflection.py

@@ -14,6 +14,7 @@ from typing import Any
 
 import dspy
 
+from .._runtime_tools import is_runtime_tool
 from . import program, types
 
 _PRIM_BY_PYTYPE: dict[Any, types.PrimKind] = {
@@ -123,9 +124,17 @@ def reflect(m: Any) -> program.Module:
     react_cls = _opt("ReAct")
     if react_cls is not None and isinstance(m, react_cls):
         tools = getattr(m, "tools", None) or {}
-        # Exclude DSPy's auto-injected `finish` sentinel — identity is the
-        # user-supplied tool set, not the runtime control-flow primitive.
-        names = tuple(sorted(n for n in tools if n != "finish"))
+        # Exclude runtime control tools. DSPy supplies `finish`; a hosted worker may
+        # add marked platform tools that are absent from the authored program. Check
+        # the explicit marker rather than a name, so a user's similarly named tool
+        # remains part of the program's identity.
+        names = tuple(
+            sorted(
+                name
+                for name, tool in tools.items()
+                if name != "finish" and not (name.startswith("cmpnd_") and is_runtime_tool(tool))
+            )
+        )
         return program.ReAct(signature=project_sig(m.signature), tools=names)
 
     bestofn_cls = _opt("BestOfN")

{cmpnd-0.27.2 → cmpnd-0.27.4}/cmpnd/mcp_servers.py

@@ -696,7 +696,7 @@ def _registered_tools(url: str, timeout_s: float) -> list[PinnedTool] | None | o
             server_url=url,
             tool_name=str(tool.get("name", "")),
             schema_hash=str(tool.get("schema_hash", "")),
-            input_schema=tool.get("input_schema") or {},
+            input_schema=registry_schema(tool),
             description=str(tool.get("description", "")),
         )
         for tool in (detail.json() or {}).get("tools") or []
@@ -704,6 +704,17 @@ def _registered_tools(url: str, timeout_s: float) -> list[PinnedTool] | None | o
     ]
 
 
+def registry_schema(tool: Mapping[str, Any]) -> Mapping[str, Any]:
+    """Require the registry's pinned schema before constructing a callable declaration."""
+    schema = tool.get("input_schema")
+    if not isinstance(schema, dict):
+        raise ValueError(
+            f"the registry could not supply the pinned schema for tool {tool.get('name')!r}; "
+            "restore the tool registry and refresh the server before deploying"
+        )
+    return schema
+
+
 def _tool_from_pinned(pinned: PinnedTool, reference: McpToolReference) -> dspy.Tool:
     """Build the local declaration DSPy needs without a live MCP session."""
     import dspy

{cmpnd-0.27.2 → cmpnd-0.27.4}/cmpnd/packaging.py

@@ -30,6 +30,8 @@ from typing import TYPE_CHECKING, Any
 
 import typing_extensions
 
+from ._runtime_tools import is_runtime_tool
+
 if TYPE_CHECKING:
     import dspy
 
@@ -722,29 +724,11 @@ def _resolve_an_mcp_tool(
 
 
 def _generate_mcp_tool_stub(pinned: typing.Any, signature: typing.Any) -> str:
-    """The `def` a resolved MCP tool becomes in the generated program.
-
-    A declaration plus a signature, and a body that is a refusal. The deployed program
-    runs in the kernel, which has no MCP client and must never hold a credential, so the
-    worker intercepts the call before this function's body runs. Reaching the body means
-    no tool token was dispatched for it, and a body that returned something instead would
-    answer the model with a lie.
-
-    The signature is synthesized rather than `*args, **kwargs` because `dspy.RLM` builds
-    each callable stub and each prompt entry from `inspect.signature(tool.func)` — a tool
-    the model cannot see a signature for is a tool it cannot call.
-
-    The docstring's reader is the model, which is why it carries two generated sentences
-    after the server's own description. The first says who answers the call. The second
-    states the shape the result comes back as, because a deployed call returns the
-    protocol's own result object while a LOCAL run through DSPy's conversion flattens it
-    to text — so a model told only what the server says would read the dict as a string.
-    """
+    """Generate a callable declaration with the registered tool's pinned signature."""
     body_lines = [f"def {signature.name}({signature.rendered}) -> dict:"]
     body_lines.extend(_docstring_lines(pinned.description))
-    body_lines.append("    raise RuntimeError(")
-    body_lines.append(f'        "{signature.name} is served by an MCP tool server and cannot run in this process"')
-    body_lines.append("    )")
+    body_lines.append("    raise RuntimeError('this MCP tool requires a worker with registered tool support')")
+    body_lines.append(f"{signature.name} = __import__('cmpnd')._mcp_tool({signature.name})")
     return "\n".join(body_lines)
 
 
@@ -761,7 +745,7 @@ def _docstring_lines(description: str) -> list[str]:
         lines.append(f"    {line}".rstrip())
     lines.append("")
     lines.append("    Served by an MCP tool server registered to this org. The worker answers this call")
-    lines.append("    before the body runs; reaching the body means no tool token was dispatched for it.")
+    lines.append("    through a scoped capability without exposing a credential to the program.")
     lines.append("")
     lines.append('    Returns an MCP tool result: {"content": [{"type": "text", "text": ...}, ...],')
     lines.append('    "isError": bool}. Read the text parts.')
@@ -796,9 +780,54 @@ def module_tools(module: dspy.Module) -> dict[str, typing.Any]:
     return dict(tools) if isinstance(tools, dict) else {}
 
 
+def declared_module_tools(module: dspy.Module) -> dict[str, typing.Any]:
+    """Collect tools throughout a module and refuse ambiguous worker routing names."""
+    import dspy
+
+    from .mcp_servers import is_bare_mcp_tool, mcp_tool_reference
+
+    collected: dict[str, typing.Any] = {}
+    pending: list[typing.Any] = [module]
+    visited: set[int] = set()
+    while pending:
+        member = pending.pop()
+        if id(member) in visited:
+            continue
+        visited.add(id(member))
+        if isinstance(member, dict):
+            pending.extend(member.values())
+            continue
+        if isinstance(member, (list, tuple)):
+            pending.extend(member)
+            continue
+        if not isinstance(member, dspy.Module):
+            continue
+        pending.extend(vars(member).values())
+        for name, tool in module_tools(member).items():
+            if name.startswith("cmpnd_") and is_runtime_tool(tool):
+                continue
+            if name.startswith("cmpnd_"):
+                raise ValueError(
+                    f"tool name {name!r} uses the reserved cmpnd_ prefix; rename the tool before deploying"
+                )
+            if is_bare_mcp_tool(tool):
+                _resolve_an_mcp_tool(name, tool, {})
+            previous = collected.get(name)
+            if previous is not None and previous is not tool:
+                old_ref = mcp_tool_reference(previous)
+                new_ref = mcp_tool_reference(tool)
+                if old_ref is not None or new_ref is not None:
+                    if old_ref != new_ref:
+                        raise ValueError(f"tool name {name!r} refers to different tools in this program")
+            collected[name] = tool
+    return collected
+
+
 def generate_program_source(
     module: dspy.Module,
     mcp_tools: Mapping[tuple[str, str], typing.Any] | None = None,
+    *,
+    _declarations: list[dict[str, typing.Any]] | None = None,
 ) -> str:
     """Return raw Python source for module.
 
@@ -942,10 +971,19 @@ def generate_program_source(
     tool_names: list[str] = []
     mcp_declarations: list[dict[str, typing.Any]] = []
     pinned_mcp_tools = mcp_tools or {}
-    tools_dict = module_tools(module)
+    tools_dict = declared_module_tools(module)
     if tools_dict:
+        from dspy import Tool
+
         from . import mcp_servers
 
+        mcp_bindings: list[tuple[Any, str]] = []
+
+        def mcp_tool_expression(route: str, alias: str, *, wrap: bool = False) -> str:
+            if wrap or alias != route:
+                return f"dspy.Tool({route}, name={alias!r})"
+            return route
+
         for name, tool in tools_dict.items():
             if name == "finish":
                 continue
@@ -955,23 +993,108 @@ def generate_program_source(
                 # instead of a body — see [_generate_mcp_tool_stub]. The `def`'s name is
                 # the MCP tool's own, because the declaration names the tool and the
                 # worker maps that name to the token it holds.
-                signature = mcp_servers.synthesized_signature(pinned)
-                lines.append(_generate_mcp_tool_stub(pinned, signature))
-                mcp_declarations.append(
-                    {
-                        "tool": signature.name,
-                        "server": pinned.server_url,
-                        "schema_hash": pinned.schema_hash,
-                        "parameters": signature.parameter_names,
-                    }
-                )
-                tool_names.append(signature.name)
+                reference = mcp_servers.mcp_tool_reference(tool)
+                route = next((route for declared, route in mcp_bindings if declared == reference), None)
+                if route is None:
+                    signature = mcp_servers.synthesized_signature(pinned)
+                    route = signature.name
+                    lines.append(_generate_mcp_tool_stub(pinned, signature))
+                    mcp_bindings.append((reference, route))
+                    mcp_declarations.append(
+                        {
+                            "tool": route,
+                            "server": pinned.server_url,
+                            "schema_hash": pinned.schema_hash,
+                            "parameters": signature.parameter_names,
+                        }
+                    )
+                tool_names.append(mcp_tool_expression(route, name))
                 continue
             func = getattr(tool, "func", None)
             if func is not None:
                 _extract_callable_tree(func)
                 tool_names.append(name)
 
+        # A composed constructor refers to its Python bindings, which need not share
+        # the registered routing name. Rebuild those bindings from pinned declarations
+        # without carrying the live MCP session or credential into generated source.
+        if is_user_module:
+            bindings: dict[str, str] = {}
+
+            def function_binding(func: Any) -> str:
+                if not inspect.isfunction(func) or not func.__name__.isidentifier():
+                    raise ValueError("Cannot reconstruct this tool callable; deploy the authored source file")
+                _extract_callable_tree(func)
+                if func.__name__ not in emitted_sources:
+                    raise ValueError("Cannot recover tool source; deploy the authored source file")
+                return func.__name__
+
+            def contains_mcp(value: Any, seen: set[int]) -> bool:
+                if id(value) in seen:
+                    return False
+                seen.add(id(value))
+                if mcp_servers.mcp_tool_reference(value) is not None:
+                    return True
+                members = value.values() if isinstance(value, dict) else value
+                return isinstance(value, (list, tuple, dict)) and any(contains_mcp(item, seen) for item in members)
+
+            def binding_source(value: Any, ancestors: frozenset[int]) -> str:
+                if id(value) in ancestors:
+                    raise ValueError("Cannot reconstruct cyclic MCP tool bindings; deploy the authored source file")
+                ancestors = ancestors | {id(value)}
+                reference = mcp_servers.mcp_tool_reference(value)
+                if reference is not None:
+                    for declared, route in mcp_bindings:
+                        if reference == declared:
+                            alias = str(getattr(value, "name", route))
+                            return mcp_tool_expression(route, alias, wrap=True)
+                    raise ValueError(
+                        "MCP tool binding is not declared by this program; deploy the authored source file"
+                    )
+                if isinstance(value, list):
+                    return "[" + ", ".join(binding_source(item, ancestors) for item in value) + "]"
+                if isinstance(value, tuple):
+                    return "(" + "".join(binding_source(item, ancestors) + ", " for item in value) + ")"
+                if isinstance(value, dict):
+                    if not all(isinstance(key, str) for key in value):
+                        raise ValueError("MCP tool dictionaries require string keys; deploy the authored source file")
+                    return (
+                        "{"
+                        + ", ".join(f"{key!r}: {binding_source(item, ancestors)}" for key, item in value.items())
+                        + "}"
+                    )
+                if isinstance(value, Tool):
+                    name = function_binding(value.func)
+                    if not _is_literal_constant(value.args):
+                        raise ValueError("Cannot reconstruct tool arguments; deploy the authored source file")
+                    return f"dspy.Tool({name}, name={value.name!r}, desc={value.desc!r}, args={value.args!r})"
+                if callable(value):
+                    return function_binding(value)
+                if _is_literal_constant(value):
+                    return repr(value)
+                raise ValueError("Cannot reconstruct a binding containing MCP tools; deploy the authored source file")
+
+            for method_name in ("__init__", "forward"):
+                method = getattr(cls, method_name, None)
+                if not inspect.isfunction(method):
+                    continue
+                closure = inspect.getclosurevars(method)
+                for name, value in {**closure.globals, **closure.nonlocals}.items():
+                    if not contains_mcp(value, set()):
+                        continue
+                    rendered = binding_source(value, frozenset())
+                    if name in bindings and bindings[name] != rendered:
+                        raise ValueError(
+                            f"MCP tool binding {name!r} has conflicting values; deploy the authored source file"
+                        )
+                    bindings[name] = rendered
+            if bindings:
+                # Evaluate every declaration before rebinding any name: an author's
+                # alias can itself be another registered tool's routing name.
+                names = ", ".join(bindings)
+                values = ", ".join(bindings.values())
+                lines.append(f"({names},) = ({values},)")
+
     # Reconstruct the synthetic ProgramSignature class up-front (when that
     # path applies) so its annotation imports land in sig_imports *before*
     # we emit the import block below. The class text itself is appended
@@ -1009,6 +1132,9 @@ def generate_program_source(
     extra_kwargs = ""
     if tool_names:
         extra_kwargs = f", tools=[{', '.join(tool_names)}]"
+        max_iters = getattr(module, "max_iters", None)
+        if not is_user_module and isinstance(max_iters, int):
+            extra_kwargs += f", max_iters={max_iters!r}"
 
     module_assigned = False
     if sig is not None:
@@ -1073,6 +1199,8 @@ def generate_program_source(
     # decide whether an empty list means "none" or "not resolved".
     if mcp_declarations:
         lines.append(f"{MCP_TOOLS_DECLARATION} = {mcp_declarations!r}")
+        if _declarations is not None:
+            _declarations.extend(mcp_declarations)
 
     return "\n\n".join(lines)
 
@@ -1241,7 +1369,12 @@ def generate_source_zip(
     """
     import dspy
 
-    program_source = generate_program_source(module, mcp_tools=mcp_tools)
+    tool_declarations: list[dict[str, typing.Any]] = []
+    program_source = generate_program_source(
+        module,
+        mcp_tools=mcp_tools,
+        _declarations=tool_declarations,
+    )
 
     metric_filename = None
     metric_source = None
@@ -1254,7 +1387,7 @@ def generate_source_zip(
 
     lm = _extract_lm_object(module)
     declarations = lm_configuration.resolve({"default-lm": lm} if lm is not None else {}, require_all=False)
-    manifest = {
+    manifest: dict[str, typing.Any] = {
         "lm_capabilities": declarations,
         "dependency_versions": {
             "python": platform.python_version(),
@@ -1263,6 +1396,8 @@ def generate_source_zip(
         "program": "program_source.py",
         "metric": metric_filename,
     }
+    if tool_declarations:
+        manifest["tools"] = tool_declarations
 
     buf = io.BytesIO()
     with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:

{cmpnd-0.27.2 → cmpnd-0.27.4}/docs/cli.md

@@ -282,12 +282,14 @@ immediately, because the credential goes with it. The confirmation says so.
 A program built with `cmpnd.mcp_tools` deploys against exactly this registry.
 `cmpnd deploy` resolves each of the program's tool references against it before
 packaging anything — one listing read plus one read per server, and none at all
-for a program with no MCP tools — so the bundle pins the same reduced schema the
-platform will validate every call against. An unregistered server and a tool the
-registry does not list are both refused at the terminal, naming the tool, the
-server and the command that fixes it; the platform refuses the same two
-authoritatively, plus a tool that is registered but not allow-listed and a schema
-that has changed since the program was built. See
+for a program with no MCP tools — so the bundle records declarations built from the
+current reduced schema and its hash. Serve checks that hash against the current
+registry at deploy time. mcp-tools validates each call against the current stored
+schema, so a refresh can change call validation after a program was built. An
+unregistered server and a tool the registry does not list are both refused at the
+terminal, naming the tool, the server and the command that fixes it; the platform
+refuses the same two authoritatively, plus a tool that is registered but not
+allow-listed and a schema that has changed since the program was built. See
 [`sdk-instrumentation.md`](sdk-instrumentation.md) for what the bundle carries in
 place of a tool's body.
 

{cmpnd-0.27.2 → cmpnd-0.27.4}/docs/sdk-instrumentation.md

@@ -401,7 +401,8 @@ def web_search_exa(query: str, numResults: float | None = None) -> dict:
 
 
 __cmpnd_mcp_tools__ = [{'tool': 'web_search_exa', 'server': 'https://mcp.exa.ai/mcp',
-                        'schema_hash': '…', 'parameters': ['query', 'numResults']}]
+                        'schema_hash': '…',
+                        'parameters': ['query', 'numResults']}]
 ```
 
 The body is a refusal because the deployed program runs in the kernel, which has no MCP
@@ -425,6 +426,13 @@ annotation at all for a type name the table does not carry. A property name that
 Python identifier, or is a keyword, refuses the deploy — it is never mangled, because the
 name has to reach the MCP server unchanged.
 
+The SDK uses the registry's pinned, secret-free `input_schema` to construct the generated
+function signature. The source marker and generated bundle manifest retain `schema_hash`
+and `parameters`. Serve checks the hash against the registry at deploy time, and the
+worker uses the parameters for positional binding. Runtime schema inspection reads the
+current stored schema through credentialed-egress and mcp-tools, so it does not rely on a
+schema copy in the program bundle.
+
 ### Direct local MCP discovery supports two client generations
 
 When registry lookup falls back to a direct local connection, the SDK lists tools
@@ -605,3 +613,26 @@ A new hand-rolled serializer on any of those paths reopens the hole. `tests/test
 - [`./optimization-tracking.md`](../../docs/optimization-tracking.md) — how `auto_instrument`'s GEPA patch and `cmpnd/optimizers/tracker.py` turn a `GEPA.compile` call into an `OptimizationRun` with linked evals.
 - The `cmpnd-testing` skill + [`../AGENTS.md`](../AGENTS.md) § "Running Tests & Checks" — patterns for writing callback tests against real databases, including `clear_context()` usage.
 - [`serve/DB.md`](../../serve/DB.md) — the Postgres schema these payloads land in.
+
+### Registered MCP tools in ReAct
+
+`cmpnd.mcp_tools` declares registered tools for ReAct and RLM, including modules
+that contain them. Deployment resolves those declarations against the organization's
+registry and pins their schemas. Bare MCP session closures cannot be packaged.
+Conflicting tools with the same routing name are refused.
+Generated composed programs retain global and closure aliases for registered tools,
+including aliases stored in lists, tuples, or dictionaries. The packager rebuilds
+these bindings from pinned declarations without copying live MCP sessions.
+Generated mixed-tool bindings require ordinary tools to be named Python functions.
+Use authored-source deployment for partials, callable instances, lambdas, or bound methods.
+
+The WASM kernel calls tools through a typed worker import. The worker holds the
+scoped tokens and returns the MCP result document. Optional arguments omitted by
+the program remain omitted. ReAct's tool callbacks produce the application span;
+the worker adds transport measurements to that span using its correlation ID.
+
+The worker reserves the `cmpnd_` prefix for platform tools. Deployment refuses an
+authored tool that uses this prefix and asks the author to rename it. Platform tools
+that the worker adds while a program runs carry a private, copy-stable provenance token.
+Only tools carrying that token stay out of the program's identity and generated bundle.
+Setting a similarly named attribute does not grant platform provenance.

{cmpnd-0.27.2 → cmpnd-0.27.4}/pyproject.toml

@@ -5,7 +5,7 @@ name = "cmpnd"
 # it's new) — no git tags. Bump with `uv version --bump {minor,patch}` or by
 # hand. Runtime `cmpnd.__version__` reads installed metadata, so it tracks
 # this automatically. See docs/plans/2026-07-02-sdk-pypi-tag-free-publish.md.
-version = "0.27.2"
+version = "0.27.4"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.10"

{cmpnd-0.27.2 → cmpnd-0.27.4}/tests/e2e/test_traces_read.py

@@ -9,6 +9,8 @@ mismatch a mocked transport cannot. Skipped unless CMPND_E2E_API_KEY is set
 
 from __future__ import annotations
 
+import time
+
 import dspy
 import pytest
 
@@ -26,16 +28,28 @@ class TestTracesReadE2E:
         assert trace_id is not None, "no trace captured"
         program_hash = server_client.get_trace(trace_id)["trace"]["program_signature_hash"]
 
-        # list by the program that produced it finds the trace.
-        page = cmpnd.traces.list(hash=str(program_hash), limit=50, api_key=CMPND_E2E_API_KEY, endpoint=E2E_ENDPOINT)
-        assert trace_id in [t["trace_id"] for t in page["traces"]]
-
-        # show returns the trace and its spans.
+        # Detail reads the ingested source without waiting for collection projection.
         detail = cmpnd.traces.show(trace_id, api_key=CMPND_E2E_API_KEY, endpoint=E2E_ENDPOINT)
         assert detail["trace"]["trace_id"] == trace_id
         assert isinstance(detail["spans"], list)
         assert len(detail["spans"]) >= 1
 
+        # Collection publication is asynchronous. Allow its 30-second idle
+        # cooldown plus processing time, polling the same trace rather than
+        # rerunning the program and restarting the freshness window.
+        deadline = time.monotonic() + 90
+        while True:
+            page = cmpnd.traces.list(hash=str(program_hash), limit=50, api_key=CMPND_E2E_API_KEY, endpoint=E2E_ENDPOINT)
+            listed_ids = [t["trace_id"] for t in page["traces"]]
+            if trace_id in listed_ids:
+                break
+            remaining = deadline - time.monotonic()
+            assert remaining > 0, (
+                f"Trace {trace_id} is readable in detail but absent from its program's collection after 90s; "
+                f"program={program_hash}, last listed trace IDs={listed_ids}"
+            )
+            time.sleep(min(2, remaining))
+
     def test_show_missing_trace_raises(self):
         with pytest.raises(cmpnd.ApiError):
             cmpnd.traces.show("00000000-0000-0000-0000-000000000000", api_key=CMPND_E2E_API_KEY, endpoint=E2E_ENDPOINT)