rote-cli 0.13.0__tar.gz → 0.14.0__tar.gz

{rote_cli-0.13.0 → rote_cli-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: rote-cli
-Version: 0.13.0
+Version: 0.14.0
 Summary: Compile AI agent skills into cheap, fast, deterministic pipelines that run without an LLM in the loop
 Project-URL: Homepage, https://roteskills.com
 Project-URL: Repository, https://github.com/trevhud/rote
@@ -29,11 +29,11 @@ Requires-Dist: pyyaml>=6.0
 Provides-Extra: api
 Requires-Dist: anthropic>=0.89; extra == 'api'
 Provides-Extra: dbos
-Requires-Dist: dbos>=2.26; extra == 'dbos'
+Requires-Dist: dbos<3,>=2.26; extra == 'dbos'
 Provides-Extra: dev
 Requires-Dist: anthropic>=0.89; extra == 'dev'
-Requires-Dist: dbos>=2.26; extra == 'dev'
-Requires-Dist: fastmcp>=3.4.2; extra == 'dev'
+Requires-Dist: dbos<3,>=2.26; extra == 'dev'
+Requires-Dist: fastmcp<4,>=3.4.2; extra == 'dev'
 Requires-Dist: httpx>=0.28; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: openai>=2.45; extra == 'dev'
@@ -43,12 +43,12 @@ Requires-Dist: ruff>=0.6; extra == 'dev'
 Requires-Dist: temporalio>=1.7; extra == 'dev'
 Requires-Dist: types-pyyaml; extra == 'dev'
 Provides-Extra: mcp
-Requires-Dist: fastmcp>=3.4.2; extra == 'mcp'
+Requires-Dist: fastmcp<4,>=3.4.2; extra == 'mcp'
 Requires-Dist: httpx>=0.28; extra == 'mcp'
 Provides-Extra: openai-api
 Requires-Dist: openai>=2.45; extra == 'openai-api'
 Provides-Extra: serve
-Requires-Dist: fastmcp>=3.4.2; extra == 'serve'
+Requires-Dist: fastmcp<4,>=3.4.2; extra == 'serve'
 Requires-Dist: httpx>=0.28; extra == 'serve'
 Provides-Extra: temporal
 Requires-Dist: temporalio>=1.7; extra == 'temporal'
@@ -257,6 +257,24 @@ override with `--agent`. The output directory splits into `compiled/`
 (the agent's `pipeline.yaml`, `extracted/`, `signatures/`, eval seeds,
 and a `compile-report.md`) and `runtime/<runtime>/` (the adapter's
 emitted code + a README on how to run, signal gates, and deploy).
+`compiled/compile-metrics.json` preserves final token counts, session ID,
+and the driver's cost estimate before emission starts, so an adapter
+failure does not lose the paid run's metrics. Missing final output stays
+null with `usage_complete: false`; unchanged updates retain prior metrics.
+
+Local `api` and `openai-api` compilation automatically discovers your
+registered, authenticated MCP servers and exposes their read-only tools.
+Pass `--no-mcp` to skip that discovery and compile without live MCP calls:
+
+```sh
+rote compile examples/bdr-outreach/skill --local --agent api --no-mcp --out /tmp/bdr-compiled
+```
+
+This leaves the emitted pipeline's MCP bindings intact. The flag also works
+with `rote analyze` and with an API driver selected through config or
+auto-detection. It rejects cloud compilation, subprocess drivers, and
+`--baseline`, whose raw skill run uses its own MCP tools. API drivers bill
+through your API credentials.
 
 ### Other commands
 
@@ -501,6 +519,9 @@ rote/
   archetype: a bounded browser-automation loop stays one agent node
   while the date math, filtering, and reporting around it compile to
   code, plus the measured runs that forced the loop-aware cost model
+- [`examples/rote-compile/`](examples/rote-compile/): the compiler compiling
+  its own core skill, with preserved artifacts and an offline audit of
+  the generated workflow's runtime and data-flow failures
 
 ---
 
@@ -508,17 +529,19 @@ rote/
 
 In rough priority order:
 
-1. **Re-compile BDR end-to-end with `signature_spec`**: the bundled IR
-   was hand-extended with structured schemas; the rubric now teaches the
-   field, but no real run has produced one yet.
-2. **Pre-filter as a `pure_function` node**: today hard thresholds are
-   lifted into a judge's `forward()`, which works for Temporal but not
-   Cloudflare; a separate node makes the short-circuit uniform.
-3. **More example skills**: BDR is one shape; research-heavy,
-   retrieval-heavy, and code-review skills stress the IR differently.
-4. **The compiler compiling itself**: `rote-compile` is a SKILL.md;
-   pointing `rote compile` at it should crystallize its rubric-grade
-   pieces and leave only the genuinely fuzzy judgments in the loop.
+1. **Pre-filter as a `pure_function` node**: today hard thresholds are
+   lifted into a judge's `forward()`, which works for the Python
+   runtimes but not the TypeScript ones; a separate node makes the
+   short-circuit uniform across all six.
+2. **Make self-compilation executable**: the
+   [preserved core-skill run](examples/rote-compile/) produced valid IR,
+   and runtime emission now succeeds. Its offline audit still has
+   data-flow and agent-result contract failures. Close those gaps before
+   treating it as a working replacement compiler.
+3. **More example skills**: four archetypes are covered today (BDR
+   outreach, 100%-roteness, data-heavy, agent-loop). Research-heavy,
+   retrieval-heavy, and code-review skills each stress the IR in ways
+   none of those four do.
 
 ---
 

{rote_cli-0.13.0 → rote_cli-0.14.0}/README.md

@@ -201,6 +201,24 @@ override with `--agent`. The output directory splits into `compiled/`
 (the agent's `pipeline.yaml`, `extracted/`, `signatures/`, eval seeds,
 and a `compile-report.md`) and `runtime/<runtime>/` (the adapter's
 emitted code + a README on how to run, signal gates, and deploy).
+`compiled/compile-metrics.json` preserves final token counts, session ID,
+and the driver's cost estimate before emission starts, so an adapter
+failure does not lose the paid run's metrics. Missing final output stays
+null with `usage_complete: false`; unchanged updates retain prior metrics.
+
+Local `api` and `openai-api` compilation automatically discovers your
+registered, authenticated MCP servers and exposes their read-only tools.
+Pass `--no-mcp` to skip that discovery and compile without live MCP calls:
+
+```sh
+rote compile examples/bdr-outreach/skill --local --agent api --no-mcp --out /tmp/bdr-compiled
+```
+
+This leaves the emitted pipeline's MCP bindings intact. The flag also works
+with `rote analyze` and with an API driver selected through config or
+auto-detection. It rejects cloud compilation, subprocess drivers, and
+`--baseline`, whose raw skill run uses its own MCP tools. API drivers bill
+through your API credentials.
 
 ### Other commands
 
@@ -445,6 +463,9 @@ rote/
   archetype: a bounded browser-automation loop stays one agent node
   while the date math, filtering, and reporting around it compile to
   code, plus the measured runs that forced the loop-aware cost model
+- [`examples/rote-compile/`](examples/rote-compile/): the compiler compiling
+  its own core skill, with preserved artifacts and an offline audit of
+  the generated workflow's runtime and data-flow failures
 
 ---
 
@@ -452,17 +473,19 @@ rote/
 
 In rough priority order:
 
-1. **Re-compile BDR end-to-end with `signature_spec`**: the bundled IR
-   was hand-extended with structured schemas; the rubric now teaches the
-   field, but no real run has produced one yet.
-2. **Pre-filter as a `pure_function` node**: today hard thresholds are
-   lifted into a judge's `forward()`, which works for Temporal but not
-   Cloudflare; a separate node makes the short-circuit uniform.
-3. **More example skills**: BDR is one shape; research-heavy,
-   retrieval-heavy, and code-review skills stress the IR differently.
-4. **The compiler compiling itself**: `rote-compile` is a SKILL.md;
-   pointing `rote compile` at it should crystallize its rubric-grade
-   pieces and leave only the genuinely fuzzy judgments in the loop.
+1. **Pre-filter as a `pure_function` node**: today hard thresholds are
+   lifted into a judge's `forward()`, which works for the Python
+   runtimes but not the TypeScript ones; a separate node makes the
+   short-circuit uniform across all six.
+2. **Make self-compilation executable**: the
+   [preserved core-skill run](examples/rote-compile/) produced valid IR,
+   and runtime emission now succeeds. Its offline audit still has
+   data-flow and agent-result contract failures. Close those gaps before
+   treating it as a working replacement compiler.
+3. **More example skills**: four archetypes are covered today (BDR
+   outreach, 100%-roteness, data-heavy, agent-loop). Research-heavy,
+   retrieval-heavy, and code-review skills each stress the IR in ways
+   none of those four do.
 
 ---
 

{rote_cli-0.13.0 → rote_cli-0.14.0}/pyproject.toml

@@ -69,14 +69,14 @@ openai-api = [
     "openai>=2.45",
 ]
 dbos = [
-    "dbos>=2.26",
+    "dbos>=2.26,<3",
 ]
 serve = [
-    "fastmcp>=3.4.2",
+    "fastmcp>=3.4.2,<4",
     "httpx>=0.28",
 ]
 mcp = [
-    "fastmcp>=3.4.2",
+    "fastmcp>=3.4.2,<4",
     "httpx>=0.28",
 ]
 dev = [
@@ -88,8 +88,8 @@ dev = [
     "temporalio>=1.7",
     "anthropic>=0.89",
     "openai>=2.45",
-    "dbos>=2.26",
-    "fastmcp>=3.4.2",
+    "dbos>=2.26,<3",
+    "fastmcp>=3.4.2,<4",
     "httpx>=0.28",
 ]
 

{rote_cli-0.13.0 → rote_cli-0.14.0}/src/rote/__init__.py

@@ -1,3 +1,3 @@
 """rote — compile fuzzy AI skills into deterministic workflows."""
 
-__version__ = "0.13.0"
+__version__ = "0.14.0"

{rote_cli-0.13.0 → rote_cli-0.14.0}/src/rote/adapters/__init__.py

@@ -56,9 +56,17 @@ def _cloudflare_adapter_factory(**options: Any) -> Adapter:
     from rote.adapters.cloudflare import CloudflareAdapter, CloudflareAdapterConfig
 
     backend = _validated_backend(options)
-    if backend is None:
+    mcp_client = options.get("mcp_client")
+    if mcp_client not in (None, "direct", "binding"):
+        raise ValueError(f"mcp_client must be 'direct' or 'binding', got {mcp_client!r}")
+    if backend is None and mcp_client is None:
         return CloudflareAdapter()
-    return CloudflareAdapter(CloudflareAdapterConfig(external_backend=backend))
+    return CloudflareAdapter(
+        CloudflareAdapterConfig(
+            external_backend=backend or "mcp",
+            mcp_client=mcp_client or "direct",
+        )
+    )
 
 
 def _source_dir(options: dict[str, Any]) -> Path | None:

{rote_cli-0.13.0 → rote_cli-0.14.0}/src/rote/adapters/_py_common.py

@@ -232,38 +232,47 @@ class _SchemaToPydantic:
 
     The Python analog of the Cloudflare adapter's ``json_schema_to_zod``.
     Named ``$defs`` become named classes / ``Literal`` aliases; inline
-    object schemas get synthesized names. Blocks are accumulated in
-    dependency order (a class is emitted only after everything it
-    references), so the generated module imports cleanly top-to-bottom.
+    object schemas get synthesized names. Each root schema resolves its
+    own definitions; generated names and dependency-ordered blocks are
+    shared across the module.
     """
 
-    def __init__(self) -> None:
+    def __init__(self, *, reserved_names: tuple[str, ...] = ()) -> None:
         self._defs: dict[str, dict[str, Any]] = {}
         self._blocks: list[str] = []
         self._emitted: dict[str, str] = {}  # $def name -> python name
         self._in_progress: set[str] = set()
-        self._used_names: set[str] = set()
+        self._used_names: set[str] = {
+            *keyword.kwlist,
+            *reserved_names,
+            "Any",
+            "Literal",
+            "BaseModel",
+            "ConfigDict",
+            "Field",
+            "PROMPT",
+            "MODEL",
+            "TEMPERATURE",
+        }
         self.uses_literal = False
         self.uses_config_dict = False
         self.uses_field = False
 
     # ── public API ──
 
-    def add_defs(self, defs: dict[str, Any]) -> None:
-        for name, schema in defs.items():
-            if name in self._defs and self._defs[name] != schema:
-                raise ValueError(
-                    f"signature emission: $defs entry {name!r} appears in both input "
-                    f"and output schemas with different definitions"
-                )
-            self._defs[name] = schema
-
     def emit_root(self, class_name: str, schema: dict[str, Any]) -> None:
         if schema.get("type") != "object":
             raise ValueError(
                 f"signature emission: root signature schema for {class_name} must be "
                 f"an object schema, got type={schema.get('type')!r}"
             )
+        # A #/$defs reference belongs to its root document. Sharing this
+        # cache across input/output can bind even identical wrappers to the
+        # wrong nested definition. Only Python symbol allocation is global.
+        self._defs = schema.get("$defs", {})
+        self._emitted.clear()
+        self._in_progress.clear()
+        self._used_names.add(class_name)
         self._emit_object_class(class_name, schema)
 
     @property
@@ -498,9 +507,7 @@ def emit_signature_module(
     spec = node.signature_spec
     pascal = _to_pascal_case(node.id)
 
-    converter = _SchemaToPydantic()
-    converter.add_defs(spec.input_schema.get("$defs", {}))
-    converter.add_defs(spec.output_schema.get("$defs", {}))
+    converter = _SchemaToPydantic(reserved_names=(pascal, f"{pascal}Input", f"{pascal}Output"))
     converter.emit_root(f"{pascal}Input", spec.input_schema)
     converter.emit_root(f"{pascal}Output", spec.output_schema)
 

{rote_cli-0.13.0 → rote_cli-0.14.0}/src/rote/adapters/_ts_common.py

@@ -1699,7 +1699,9 @@ function isUnauthorizedWorkers(err: unknown): boolean {
 """
 
 
-def emit_workers_mcp_call_module(node: Node, *, generated_by: str) -> str:
+def emit_workers_mcp_call_module(
+    node: Node, *, generated_by: str, mcp_client: str = "direct"
+) -> str:
     """Emit ``src/extracted/<id>.ts`` as a working Workers MCP call.
 
     Same module path and function name as the stub, but the function
@@ -1735,8 +1737,23 @@ def emit_workers_mcp_call_module(node: Node, *, generated_by: str) -> str:
         f" * {desc_first}",
         " *",
         f" * Auto-generated by {generated_by}: invokes tool {binding.tool!r} on MCP",
-        f" * server {binding.server!r} over Streamable HTTP, authenticated from",
-        f" * Worker secrets provisioned by `rote mcp export {binding.server}`.",
+        # The provisioning sentence has to match the helper this build
+        # actually emitted. Binding mode reads no per-server secrets at
+        # all, and this header is the file an operator opens when a call
+        # fails, so naming the wrong mechanism sends them to configure
+        # secrets nothing will ever read.
+        *(
+            [
+                f" * server {binding.server!r} through the platform's ROTE_MCP service",
+                " * binding. The platform provisions the connection; this build reads",
+                " * no per-server secrets.",
+            ]
+            if mcp_client == "binding"
+            else [
+                f" * server {binding.server!r} over Streamable HTTP, authenticated from",
+                f" * Worker secrets provisioned by `rote mcp export {binding.server}`.",
+            ]
+        ),
         " * Swap to a direct vendor-SDK call with `rote emit --backend api`.",
         *mandatory_lines,
         " */",
@@ -1762,6 +1779,337 @@ def emit_workers_mcp_call_module(node: Node, *, generated_by: str) -> str:
     return "\n".join(lines)
 
 
+#: Source of the BINDING variant of ``src/extracted/_roteMcp.ts`` —
+#: emitted when the Cloudflare adapter runs with ``mcp_client="binding"``.
+#: Same exported surface as :data:`ROTE_MCP_WORKERS_HELPER_TS` (the node
+#: modules and agent loops import both identically), but every operation
+#: is delegated to a platform-provisioned ``ROTE_MCP`` service binding:
+#: no token store, no OAuth refresh, no per-server secrets, and no MCP
+#: SDK dependency. Every proxy call carries a signed caller-auth object
+#: built from dispatcher-injected env vars (``ROTE_TENANT_ID`` /
+#: ``ROTE_PIPELINE`` / ``ROTE_RUN_ID`` / ``ROTE_MCP_SIG``) so tenant
+#: isolates cannot impersonate each other. The platform proxy signals a
+#: credential problem with a plain Error whose message starts with
+#: ``ROTE_MCP_AUTH_NEEDED:`` (RPC boundaries strip class identity, so
+#: the signal rides in the message); the helper rethrows that as
+#: RoteMcpAuthNeeded so the emitted park-on-auth loop works unchanged.
+ROTE_MCP_BINDING_HELPER_TS = """/**
+ * MCP helper for platform-managed connections (generated by rote — do
+ * not edit; the source of truth is
+ * rote.adapters._ts_common.ROTE_MCP_BINDING_HELPER_TS).
+ *
+ * Every MCP operation is delegated to the `ROTE_MCP` service binding —
+ * an RPC stub the hosting platform provisions on this Worker. The
+ * platform owns endpoint resolution, credentials, and token refresh, so
+ * this variant carries no token store, no OAuth, and no per-server
+ * secrets. Every call carries a signed caller-auth object built from
+ * the dispatcher-injected ROTE_TENANT_ID / ROTE_PIPELINE / ROTE_RUN_ID /
+ * ROTE_MCP_SIG variables, so tenant isolates cannot impersonate each
+ * other. When the platform proxy reports a missing or dead credential
+ * (a plain Error whose message starts with "ROTE_MCP_AUTH_NEEDED:"),
+ * the helper rethrows RoteMcpAuthNeeded so the workflow's park-on-auth
+ * loop suspends the instance until the connection is re-authorized.
+ */
+
+/** One tool as the server advertises it. */
+export interface McpToolSpec {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+
+/** ROTE_MCP_SIG authenticates tenant + pipeline; run_id is attribution. */
+export interface RoteMcpAuth {
+    tenant_id: string;
+    pipeline: string;
+    run_id?: string;
+    sig: string;
+}
+
+/** One call's outcome, as the proxy reports it. */
+export interface RoteMcpCallResult {
+    /** Text string, or the tool's structured object. */
+    content: unknown;
+    is_error: boolean;
+}
+
+/** One tool as the proxy advertises it (snake_case wire shape). */
+export interface RoteMcpToolInfo {
+    name: string;
+    description: string | null;
+    input_schema: unknown;
+}
+
+/** The platform's MCP proxy, provisioned as an RPC service binding. */
+export interface RoteMcpBinding {
+    call(
+        auth: RoteMcpAuth,
+        server: string,
+        tool: string,
+        args: Record<string, unknown>,
+    ): Promise<RoteMcpCallResult>;
+    listTools(auth: RoteMcpAuth, server: string): Promise<RoteMcpToolInfo[]>;
+}
+
+export interface RoteMcpEnv {
+    ROTE_MCP: RoteMcpBinding;
+    [key: string]: unknown;
+}
+
+/**
+ * The MCP server's platform connection needs to be re-authorized.
+ * Detect with isRoteMcpAuthNeeded(), never `instanceof`: Workflows
+ * serialize errors across hibernation and replay boundaries — class
+ * identity is lost, `name` survives.
+ */
+export class RoteMcpAuthNeeded extends Error {
+    readonly server: string;
+    readonly reason: string;
+
+    constructor(server: string, reason: string) {
+        super(
+            `MCP server '${server}' needs (re)authentication — ${reason}. ` +
+                `Re-authorize the connection on the platform hosting this worker.`,
+        );
+        this.name = "RoteMcpAuthNeeded";
+        this.server = server;
+        this.reason = reason;
+    }
+}
+
+/** True if a RoteMcpAuthNeeded hides anywhere in the error tree. */
+export function isRoteMcpAuthNeeded(err: unknown): boolean {
+    let node: unknown = err;
+    for (let depth = 0; node != null && depth < 16; depth++) {
+        const e = node as { name?: unknown; errors?: unknown; cause?: unknown };
+        if (e.name === "RoteMcpAuthNeeded") return true;
+        if (Array.isArray(e.errors) && e.errors.some((sub) => isRoteMcpAuthNeeded(sub))) {
+            return true;
+        }
+        node = e.cause;
+    }
+    return false;
+}
+
+// Concrete JSON types — same rationale as the direct helper: step.do
+// constrains callback returns to Rpc.Serializable, which `unknown`
+// members do not satisfy.
+export type JsonValue = string | number | boolean | null | JsonValue[] | JsonObject;
+export type JsonObject = { [key: string]: JsonValue };
+
+/** The platform proxy's auth-failure contract: errors arrive as plain
+ * Error (the RPC boundary strips class identity), so the signal rides
+ * in the message prefix. */
+const AUTH_PREFIX = "ROTE_MCP_AUTH_NEEDED:";
+
+function translate(err: unknown, server: string): unknown {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.startsWith(AUTH_PREFIX)) {
+        let reason = msg.slice(AUTH_PREFIX.length).trim();
+        // The proxy's detail leads with the server name (its parse token);
+        // RoteMcpAuthNeeded's own message already names the server, so drop
+        // the leading token rather than saying it twice.
+        if (reason === server) {
+            reason = "";
+        } else if (reason.startsWith(`${server} `)) {
+            reason = reason.slice(server.length + 1).trim();
+        }
+        return new RoteMcpAuthNeeded(
+            server,
+            reason || "the platform reports the connection needs re-authorization",
+        );
+    }
+    return err;
+}
+
+function requireBinding(env: RoteMcpEnv): void {
+    if (!env.ROTE_MCP) {
+        throw new Error(
+            "the ROTE_MCP service binding is not configured — this build " +
+                "delegates MCP calls to the hosting platform, which must " +
+                "provision the binding",
+        );
+    }
+}
+
+function requireVar(env: RoteMcpEnv, name: string): string {
+    const value = env[name];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(
+            `the ${name} variable is not set — binding-mode MCP runs only on ` +
+                "the platform, whose dispatcher injects it into the isolate",
+        );
+    }
+    return value;
+}
+
+/** The signed caller identity sent on every proxy call. */
+function buildAuth(env: RoteMcpEnv): RoteMcpAuth {
+    // ROTE_MCP_SIG first: its absence is the clearest sign this build is
+    // running off-platform, and the config error should say so.
+    const sig = requireVar(env, "ROTE_MCP_SIG");
+    const auth: RoteMcpAuth = {
+        tenant_id: requireVar(env, "ROTE_TENANT_ID"),
+        pipeline: requireVar(env, "ROTE_PIPELINE"),
+        sig,
+    };
+    const runId = env.ROTE_RUN_ID;
+    if (typeof runId === "string" && runId.length > 0) {
+        auth.run_id = runId;
+    }
+    return auth;
+}
+
+/**
+ * Call one tool on an MCP server through the platform proxy.
+ *
+ * `is_error` results throw exactly the way the direct helper treats
+ * `result.isError`, and string content is JSON-parsed the way the
+ * direct helper parses text blocks — so a workflow step behaves the
+ * same under either client mode.
+ */
+export async function callMcpTool(
+    env: RoteMcpEnv,
+    server: string,
+    _pipelineUrl: string | null,
+    tool: string,
+    args: Record<string, unknown>,
+): Promise<JsonObject> {
+    requireBinding(env);
+    const auth = buildAuth(env);
+    let result: RoteMcpCallResult;
+    try {
+        result = await env.ROTE_MCP.call(auth, server, tool, args);
+    } catch (err) {
+        throw translate(err, server);
+    }
+    if (result.is_error) {
+        throw new Error(
+            `MCP tool '${tool}' on '${server}' returned an error: ` +
+                JSON.stringify(result.content),
+        );
+    }
+    const content = result.content;
+    if (typeof content === "string") {
+        return (content ? JSON.parse(content) : {}) as JsonObject;
+    }
+    return (content ?? {}) as JsonObject;
+}
+
+/**
+ * Every tool `server` advertises, fetched through the platform proxy.
+ *
+ * The proxy's snake_case wire shape (`input_schema`, nullable
+ * description) is normalized into McpToolSpec so bindAgentTools and the
+ * agent loops see the same shape under either client mode.
+ */
+export async function listMcpTools(
+    env: RoteMcpEnv,
+    server: string,
+    _pipelineUrl: string | null,
+): Promise<McpToolSpec[]> {
+    requireBinding(env);
+    const auth = buildAuth(env);
+    let tools: RoteMcpToolInfo[];
+    try {
+        tools = await env.ROTE_MCP.listTools(auth, server);
+    } catch (err) {
+        throw translate(err, server);
+    }
+    return tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description ?? "",
+        inputSchema: (tool.input_schema ?? {
+            type: "object",
+            properties: {},
+        }) as Record<string, unknown>,
+    }));
+}
+
+/** A tool bound to a callable — structurally a BoundTool for the agent loop. */
+export interface BoundMcpTool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    run: (args: Record<string, unknown>) => Promise<JsonObject>;
+}
+
+/**
+ * Candidate servers for tool discovery — same contract as the direct
+ * helper: the pipeline's declared servers, with ROTE_MCP_SERVERS
+ * replacing the list wholesale when an operator overrides it.
+ */
+function agentServerNames(env: RoteMcpEnv, declared: string[]): string[] {
+    const override = env.ROTE_MCP_SERVERS;
+    if (typeof override === "string" && override.length > 0) {
+        return override
+            .split(",")
+            .map((name) => name.trim())
+            .filter(Boolean);
+    }
+    return [...new Set(declared)].sort();
+}
+
+/**
+ * Bind the tools an agent_loop declared to callables the loop can invoke.
+ *
+ * Same contract as the direct helper: discovery is best-effort per server
+ * (a server that is down may not be one this loop needed), a declared
+ * tool no reachable server provides is fatal, and an auth failure that
+ * plausibly explains the gap is rethrown so the Workflow parks on it.
+ */
+export async function bindAgentTools(
+    env: RoteMcpEnv,
+    allowed: string[],
+    declaredServers: string[],
+    serverUrls: Record<string, string | null> = {},
+    toolServers: Record<string, string> = {},
+): Promise<BoundMcpTool[]> {
+    const wanted = new Set(allowed);
+    const bound = new Map<string, BoundMcpTool>();
+    const failures: unknown[] = [];
+
+    for (const server of agentServerNames(env, declaredServers)) {
+        const url = serverUrls[server] ?? null;
+        let specs: McpToolSpec[];
+        try {
+            specs = await listMcpTools(env, server, url);
+        } catch (err) {
+            failures.push(err);
+            continue;
+        }
+        for (const spec of specs) {
+            if (!wanted.has(spec.name) || bound.has(spec.name)) continue;
+            // Resolved tools bind only from their own server — see the
+            // direct helper's twin for why first-wins is not good enough.
+            const pinned = toolServers[spec.name];
+            if (pinned !== undefined && pinned !== server) continue;
+            bound.set(spec.name, {
+                name: spec.name,
+                description: spec.description,
+                parameters: spec.inputSchema,
+                run: (args) => callMcpTool(env, server, url, spec.name, args),
+            });
+        }
+    }
+
+    const missing = allowed.filter((name) => !bound.has(name));
+    if (missing.length > 0) {
+        const authFailure = failures.find((err) => isRoteMcpAuthNeeded(err));
+        if (authFailure) throw authFailure;
+        const detail = failures
+            .map((err) => (err instanceof Error ? err.message : String(err)))
+            .join("; ");
+        throw new Error(
+            `agent tools not provided by any reachable MCP server: ${missing.join(", ")}` +
+                (detail ? ` (unreachable: ${detail})` : ""),
+        );
+    }
+    return [...bound.values()];
+}
+"""
+
+
 # ───────── signatures/_roteInference.ts (agent loops) ─────────
 
 #: The default Workers AI model for an agent loop. Tool-capable and the