rote-cli 0.11.0__tar.gz → 0.12.0__tar.gz

{rote_cli-0.11.0 → rote_cli-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rote-cli
-Version: 0.11.0
+Version: 0.12.0
 Summary: Compile fuzzy AI skills into deterministic, reliable workflows
 Project-URL: Homepage, https://github.com/trevhud/rote
 Project-URL: Repository, https://github.com/trevhud/rote

{rote_cli-0.11.0 → rote_cli-0.12.0}/skills/rote-compile/references/ir-schema.md

@@ -336,6 +336,9 @@ the loop.
   tools:
     - zoominfo_search_contacts
     - zoominfo_search_companies
+  tool_servers:
+    zoominfo_search_contacts: zoominfo
+    zoominfo_search_companies: zoominfo
   loop_body:
     - enrich_contact_batch
     - vet_contact
@@ -345,6 +348,16 @@ the loop.
   timeout: 15m
 ```
 
+**Note on `tool_servers`:** map every tool you can to the MCP server
+that provides it. `tools` names tools without a server, and that gap is
+not cosmetic — the pipeline's MCP requirements are derived from server
+names, so a pipeline whose only MCP usage is an agent loop reports *no
+required servers at all* and the user is never told to authenticate.
+Fill in the entries you're confident about and omit the rest; a partial
+map is valid, and an unmapped tool is resolved at run time (more
+fragile, and impossible on Cloudflare, which has no local registry).
+Every key must also appear in `tools`.
+
 **Note on `loop_body`:** sub-nodes listed here must also exist as
 top-level nodes in the `nodes:` list. They're referenced from the
 loop_body but also emitted as standalone activities (so they can be

{rote_cli-0.11.0 → rote_cli-0.12.0}/skills/rote-compile/references/llm-judge-extraction.md

@@ -253,7 +253,7 @@ signature_spec:
                                   # 'openai' this reaches any OpenAI-compatible
                                   # server (Ollama, vLLM, a gateway). Only set
                                   # it when the source skill names an endpoint.
-  temperature: 0.0                # optional
+  temperature: 0.0                # DO NOT SET — see below
 ```
 
 Emitted code layers runtime overrides on top of these defaults —
@@ -261,6 +261,31 @@ Emitted code layers runtime overrides on top of these defaults —
 variables — so pick sensible defaults and let operators retarget a
 judge without re-compiling.
 
+### Never set `temperature`
+
+Leave `temperature` out of `signature_spec`. It reads like the
+obviously-right knob for a deterministic judge, and it is a trap:
+**current Anthropic models reject the parameter outright** with
+
+```
+400 invalid_request_error: `temperature` is not supported on this
+model. Remove it from your request.
+```
+
+A judge carrying `temperature: 0.0` is therefore dead on arrival
+against a current model — which is exactly where an operator's
+`ROTE_MODEL_<NODE_ID>` override points it. Found live: a graduated
+pipeline whose every judge call 400'd on the first real run.
+
+Determinism does not come from temperature anyway. It comes from the
+schema-locked decoding the adapters already emit — a forced tool call
+(Anthropic), `response_format: json_schema` (OpenAI / Workers AI). The
+output shape is pinned whatever the sampler does.
+
+If a source skill *explicitly* names a temperature, set it and know
+that emitted code turns it into a `ROTE_TEMPERATURE_<NODE_ID>`
+override whose empty value drops the parameter again.
+
 ### Deriving the JSON Schemas
 
 The Pydantic models you wrote in step 3 (input model) and step 4
@@ -294,6 +319,28 @@ entry and use `{"$ref": "#/$defs/InnerModelName"}` at the use site.
 This matches Pydantic's own emission shape and lets adapters resolve
 references with a single helper.
 
+#### A key that can be null is not a required string
+
+`required` in an *input* schema is a claim about the data a real
+upstream step will hand you, and it is the single easiest way to make
+a pipeline die on live data. A field that a tool returns as `null` —
+on drafts, on unpublished rows, on anything half-filled — must be
+either omitted from `required` or typed `{"anyOf": [{"type":
+"string"}, {"type": "null"}]}`. Emitted models make a non-required
+field `X | None = None`, so dropping it from `required` is enough.
+
+Presence is not non-nullness. An observed payload that always carries
+a `summary` key still tells you nothing about whether its value is
+ever `null`, and schema inference from observations records the key,
+not the nullability.
+
+Found live: a weekly-report pipeline judged nine posts one at a time;
+one of them had `summary: null`, the judge's input model required a
+string, and the whole workflow failed on that single element. When you
+have observed payloads (the baseline run's tool results), scan the
+values you actually saw — any `null` in a sample is proof the field
+belongs in the nullable set.
+
 ### Designing the prompt template
 
 The prompt is a Jinja-style template. Variables are addressed by the

{rote_cli-0.11.0 → rote_cli-0.12.0}/skills/rote-compile/references/node-kinds.md

@@ -170,6 +170,13 @@ Both the number of iterations and the specific queries vary per campaign.
 tools the agent may call). `loop_body` is optional and lists the IDs of
 sub-nodes the loop invokes each iteration.
 
+**Also set `tool_servers`** — tool name → the MCP server providing it —
+for every tool whose server you can identify from the skill (the same
+evidence that gives an `external_call` its `mcp.server`). Without it the
+tool is a bare name: the pipeline under-reports its MCP requirements, the
+user is never prompted to authenticate, and the emitted loop has to guess
+which server to search. A partial map is fine; guessing is not.
+
 **Common mistake:** leaving things as `agent_loop` when they could be
 crystallized. Most skills over-use this kind on their first pass because
 "the LLM was doing it" is the easiest classification. Fight the urge —

{rote_cli-0.11.0 → rote_cli-0.12.0}/src/rote/__init__.py

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

{rote_cli-0.11.0 → rote_cli-0.12.0}/src/rote/adapters/_common.py

@@ -16,7 +16,7 @@ import json
 import re
 from pathlib import Path
 
-from rote.ir import Node, Pipeline, parse_input_ref
+from rote.ir import Node, NodeKind, Pipeline, parse_input_ref
 
 # ───────── Default LLM models ─────────
 #
@@ -420,3 +420,47 @@ def check_input_refs_available(node: Node, available: set[str]) -> None:
                 f"workflow (it runs in a later wave, or is a loop-body sub-node "
                 f"with no top-level result)."
             )
+
+
+# ───────── MCP-capability refusal ─────────
+
+
+def refuse_mcp_only_nodes(pipeline: Pipeline, adapter: str) -> None:
+    """Refuse pipelines an MCP-incapable adapter cannot emit, loudly and early.
+
+    ``ir.Node`` accepts ``impl`` *or* ``mcp`` on an ``external_call`` — a
+    node carrying only an ``mcp`` binding is perfectly valid IR. Adapters
+    with no MCP backend have no module to import for such a node, so they
+    must refuse it rather than emit a call to nothing.
+
+    Reported for the whole pipeline at once, before any file is written,
+    so the user fixes every offending node in one pass instead of
+    rediscovering them one re-emit at a time.
+    """
+    orphans = [
+        n.id
+        for n in pipeline.nodes
+        if n.kind is NodeKind.EXTERNAL_CALL and n.impl is None and n.mcp is not None
+    ]
+    if not orphans:
+        return
+    raise ValueError(
+        f"{adapter} adapter: pipeline {pipeline.name!r} contains external_call "
+        f"node(s) [{', '.join(orphans)}] bound to an MCP server with no `impl:` — "
+        f"the {adapter} adapter has no MCP backend, so there is nothing to call. "
+        f"Emit onto a runtime that speaks MCP "
+        f"(`--runtime dbos`, `--runtime dbos-ts`, `--runtime cloudflare`, "
+        f"`--runtime inngest`), or give each node an `impl:` pointing at an "
+        f"extracted module."
+    )
+
+
+#: Fallback iteration bound when an ``agent_loop`` declares no
+#: ``termination``. An agent loop must always be bounded — an unbounded
+#: one in a durable workflow burns budget until a human notices.
+#:
+#: Lives here rather than beside either language's emitter because it is
+#: an IR policy, not a language detail: a loop compiled to Python and the
+#: same loop compiled to TypeScript must agree on how many turns "no
+#: declared bound" means.
+DEFAULT_AGENT_MAX_ITERATIONS = 10

{rote_cli-0.11.0 → rote_cli-0.12.0}/src/rote/adapters/_py_common.py

@@ -26,7 +26,12 @@ import textwrap
 from pathlib import Path
 from typing import Any
 
-from rote.adapters._common import _to_pascal_case, safe_docstring_line
+from rote.adapters._common import (
+    DEFAULT_AGENT_MAX_ITERATIONS,
+    EmitWriter,
+    _to_pascal_case,
+    safe_docstring_line,
+)
 from rote.ir import LLMSignature, Node, NodeKind, Pipeline, parse_input_ref
 
 # ───────── impl / signature path references ─────────
@@ -545,6 +550,12 @@ def emit_signature_module(
         f'MODEL = os.environ.get("ROTE_MODEL_{env_suffix}", {json.dumps(model)})\n'
         f'BASE_URL = os.environ.get("ROTE_BASE_URL_{env_suffix}"{base_url_default})'
     )
+    if spec.temperature is not None:
+        overrides_block += (
+            f"\nTEMPERATURE = os.environ.get(\n"
+            f'    "ROTE_TEMPERATURE_{env_suffix}", {json.dumps(str(spec.temperature))}\n'
+            f")"
+        )
 
     interpolate_block = textwrap.dedent(
         '''\
@@ -575,14 +586,10 @@ def emit_signature_module(
         '''
     )
 
-    if spec.client == "anthropic":
-        call_block = _emit_forward_anthropic(node, pascal, spec)
-    elif spec.client == "openai":
-        call_block = _emit_forward_openai(node, pascal, spec)
-    else:  # pragma: no cover — LLMSignature validates the client field
+    if spec.client not in ("anthropic", "openai"):  # pragma: no cover — IR-validated
         raise ValueError(f"Unsupported LLM client: {spec.client!r}")
 
-    usage_block = _emit_usage_logger(node, spec)
+    sampling_block = _emit_sampling_helper(spec)
 
     return (
         header
@@ -598,49 +605,33 @@ def emit_signature_module(
         + "\n\n\n"
         + interpolate_block
         + "\n\n"
-        + usage_block
-        + "\n\n"
-        + call_block
+        + sampling_block
+        + _emit_forward(node, pascal, spec)
     )
 
 
-def _emit_usage_logger(node: Node, spec: LLMSignature) -> str:
-    """Emit the opt-in usage log hook.
+def _emit_sampling_helper(spec: LLMSignature) -> str:
+    """Emit ``temperature`` as a runtime knob rather than a baked constant.
 
-    When ``ROTE_USAGE_LOG`` names a file, every judge call appends one
-    JSONL record with its real token usage. This is what lets
-    ``rote eval --run`` measure the compiled pipeline's actual LLM
-    footprint instead of estimating it — and it doubles as a zero-setup
-    observability tap in production. No env var → no-op, and a logging
-    failure never breaks the judge call itself.
+    Current Anthropic models **reject** ``temperature`` outright with a
+    400 ("`temperature` is not supported on this model"), so a constant
+    compiled into the judge makes it unrunnable the moment an operator
+    points ``ROTE_MODEL_<ID>`` at a newer model — which is the whole
+    point of that knob. An empty ``ROTE_TEMPERATURE_<ID>`` omits the
+    parameter entirely; unset keeps the IR's value.
 
-    Records the module-level ``MODEL`` constant, not the emit-time
-    default — operators can swap models at runtime via
-    ``ROTE_MODEL_<NODE>``, and measured usage must be priced against
-    the model that actually served the call.
+    No IR temperature → no knob and no keyword argument, which is the
+    right default: the forced tool call already pins the output shape.
     """
-    if spec.client == "openai":
-        in_attr, out_attr = "prompt_tokens", "completion_tokens"
-    else:
-        in_attr, out_attr = "input_tokens", "output_tokens"
+    if spec.temperature is None:
+        return ""
     return (
-        f"def _log_usage(response: Any) -> None:\n"
-        f'    """Append token usage as JSONL to $ROTE_USAGE_LOG, if set."""\n'
-        f'    path = os.environ.get("ROTE_USAGE_LOG")\n'
-        f"    if not path:\n"
-        f"        return\n"
-        f"    try:\n"
-        f'        usage = getattr(response, "usage", None)\n'
-        f"        record = {{\n"
-        f'            "node": {json.dumps(node.id)},\n'
-        f'            "model": MODEL,\n'
-        f'            "input_tokens": getattr(usage, {json.dumps(in_attr)}, None),\n'
-        f'            "output_tokens": getattr(usage, {json.dumps(out_attr)}, None),\n'
-        f"        }}\n"
-        f'        with open(path, "a", encoding="utf-8") as f:\n'
-        f'            f.write(json.dumps(record) + "\\n")\n'
-        f"    except OSError:\n"
-        f"        pass\n"
+        "def _sampling_kwargs() -> dict[str, Any]:\n"
+        '    """``temperature`` if configured; empty env value omits it."""\n'
+        "    if not TEMPERATURE.strip():\n"
+        "        return {}\n"
+        '    return {"temperature": float(TEMPERATURE)}\n'
+        "\n\n"
     )
 
 
@@ -652,89 +643,188 @@ def _default_model_for(
     return anthropic_default_model
 
 
-def _temperature_line(spec: LLMSignature) -> str:
-    if spec.temperature is None:
-        return ""
-    return f"            temperature={spec.temperature},\n"
+def _emit_forward(node: Node, pascal: str, spec: LLMSignature) -> str:
+    """Emit the judge class: interpolate, delegate, validate.
 
+    The vendor call itself is deliberately *not* emitted per node. It
+    lives in ``signatures/_rote_inference.py`` — the verbatim copy of
+    :mod:`rote.inference._runtime_helper` — because the same call has to
+    choose between three billing lanes (the user's Claude subscription
+    via ``claude -p``, their API key, or their rote cloud tenant) and
+    that decision is a fact about the machine, not about the pipeline.
+    Emitting it once per judge would mean N copies of the resolver
+    drifting apart inside a single generated app.
 
-def _emit_forward_anthropic(node: Node, pascal: str, spec: LLMSignature) -> str:
-    temp = _temperature_line(spec)
+    What stays here is what genuinely differs per node: the typed
+    models, the prompt, the schema, and the operator knobs.
+    """
+    kind = "Anthropic" if spec.client == "anthropic" else "OpenAI"
+    description_arg = (
+        "            tool_description=TOOL_DESCRIPTION,\n" if spec.client == "anthropic" else ""
+    )
+    sampling_arg = (
+        "            sampling=_sampling_kwargs(),\n" if spec.temperature is not None else ""
+    )
     return (
         f"class {pascal}:\n"
-        f'    """Typed LLM judge for {node.id} (Anthropic structured output)."""\n'
+        f'    """Typed LLM judge for {node.id} ({kind} structured output)."""\n'
         f"\n"
         f"    def forward(self, inputs: {pascal}Input) -> {pascal}Output:\n"
-        f"        # Lazy import: the SDK is only needed at call time, and the\n"
-        f"        # module stays importable in environments without it.\n"
-        f"        import anthropic\n"
+        f"        # Which provider serves this call — and who is billed for it —\n"
+        f"        # is resolved at runtime; see signatures/_rote_inference.py.\n"
+        f"        from signatures._rote_inference import call_judge\n"
         f"\n"
-        f"        client = anthropic.Anthropic(base_url=BASE_URL)\n"
-        f"        response = client.messages.create(\n"
+        f"        payload = call_judge(\n"
+        f"            node_id={json.dumps(node.id)},\n"
+        f"            client={json.dumps(spec.client)},\n"
         f"            model=MODEL,\n"
-        f"            max_tokens=4096,\n"
-        f"{temp}"
-        f"            tools=[\n"
-        f"                {{\n"
-        f'                    "name": {json.dumps(node.id)},\n'
-        f'                    "description": TOOL_DESCRIPTION,\n'
-        f'                    "input_schema": OUTPUT_JSON_SCHEMA,\n'
-        f"                }}\n"
-        f"            ],\n"
-        f'            tool_choice={{"type": "tool", "name": {json.dumps(node.id)}}},\n'
-        f"            messages=[\n"
-        f"                {{\n"
-        f'                    "role": "user",\n'
-        f'                    "content": _interpolate(PROMPT, inputs.model_dump(by_alias=True)),\n'
-        f"                }}\n"
-        f"            ],\n"
-        f"        )\n"
-        f"        _log_usage(response)\n"
-        f"        for block in response.content:\n"
-        f'            if block.type == "tool_use":\n'
-        f"                return {pascal}Output.model_validate(block.input)\n"
-        f"        raise RuntimeError(\n"
-        f'            "LLM did not return a tool_use block for {node.id}"\n'
+        f"            base_url=BASE_URL,\n"
+        f"            prompt=_interpolate(PROMPT, inputs.model_dump(by_alias=True)),\n"
+        f"            output_schema=OUTPUT_JSON_SCHEMA,\n"
+        f"{description_arg}"
+        f"{sampling_arg}"
         f"        )\n"
+        f"        return {pascal}Output.model_validate(payload)\n"
     )
 
 
-def _emit_forward_openai(node: Node, pascal: str, spec: LLMSignature) -> str:
-    temp = _temperature_line(spec)
-    return (
-        f"class {pascal}:\n"
-        f'    """Typed LLM judge for {node.id} (OpenAI structured output)."""\n'
-        f"\n"
-        f"    def forward(self, inputs: {pascal}Input) -> {pascal}Output:\n"
-        f"        # Lazy import: the SDK is only needed at call time, and the\n"
-        f"        # module stays importable in environments without it.\n"
-        f"        import openai\n"
-        f"\n"
-        f"        client = openai.OpenAI(base_url=BASE_URL)\n"
-        f"        response = client.chat.completions.create(\n"
-        f"            model=MODEL,\n"
-        f"{temp}"
-        f"            response_format={{\n"
-        f'                "type": "json_schema",\n'
-        f'                "json_schema": {{\n'
-        f'                    "name": {json.dumps(node.id)},\n'
-        f'                    "schema": OUTPUT_JSON_SCHEMA,\n'
-        f'                    "strict": True,\n'
-        f"                }},\n"
-        f"            }},\n"
-        f"            messages=[\n"
-        f"                {{\n"
-        f'                    "role": "user",\n'
-        f'                    "content": _interpolate(PROMPT, inputs.model_dump(by_alias=True)),\n'
-        f"                }}\n"
-        f"            ],\n"
-        f"        )\n"
-        f"        _log_usage(response)\n"
-        f"        content = response.choices[0].message.content\n"
-        f"        if not content:\n"
-        f'            raise RuntimeError("OpenAI returned no content for {node.id}")\n'
-        f"        return {pascal}Output.model_validate(json.loads(content))\n"
+def agent_loop_call(
+    node: Node, *, default_model: str, indent: str = "    ", include_local_tools: bool = True
+) -> str:
+    """Emit the ``run_agent_loop(...)`` call for an ``agent_loop`` node.
+
+    This is what replaced the ``NotImplementedError`` stub. A pipeline
+    that hands its one genuinely agentic step back to the user has not
+    graduated that step, so the emitted code runs a real bounded loop:
+    the subscription CLI when one is available and the tools are MCP,
+    otherwise the vendor SDK's own tool runner.
+
+    ``loop_body`` sub-nodes are passed as ``local_tools`` — they are
+    already-emitted, already-working steps in the same module, so the
+    agent drives them per iteration exactly as the IR describes rather
+    than the adapter guessing an order for them.
+    """
+    max_iterations = (
+        node.termination.max_iterations
+        if node.termination is not None
+        else DEFAULT_AGENT_MAX_ITERATIONS
     )
+    inner = indent + "    "
+    deep = inner + "    "
+    model_expr = f'os.environ.get("ROTE_MODEL_{node.id.upper()}", {json.dumps(default_model)})'
+    lines = [
+        f"{indent}from signatures._rote_inference import run_agent_loop",
+        "",
+        f"{indent}return run_agent_loop(",
+        f"{inner}node_id={json.dumps(node.id)},",
+        f"{inner}description={_chunked_str_literal(node.description, deep)},",
+        f"{inner}task=json.dumps(payload, default=str),",
+        f"{inner}model={model_expr},",
+    ]
+    if node.tools:
+        one_line = f"{inner}tools={_py_literal(list(node.tools))},"
+        if len(one_line) <= 98:
+            lines.append(one_line)
+        else:
+            # Emitted output is committed and ruff-linted at line-length
+            # 100, so a long tool list wraps rather than overflowing.
+            lines.append(f"{inner}tools=[")
+            lines.extend(f"{deep}{_py_literal(t)}," for t in node.tools)
+            lines.append(f"{inner}],")
+    if node.tool_servers:
+        # Resolved tool → server pins narrow the allowlist to real pairs.
+        lines.append(f"{inner}tool_servers={_py_literal(dict(sorted(node.tool_servers.items())))},")
+    if node.loop_body and include_local_tools:
+        lines.append(f"{inner}local_tools={{")
+        for sub in node.loop_body:
+            lines.append(f"{inner}    {json.dumps(sub)}: {sub},")
+        lines.append(f"{inner}}},")
+    lines.append(f"{inner}max_iterations={max_iterations},")
+    if node.termination is not None:
+        condition = _chunked_str_literal(node.termination.condition, deep)
+        lines.append(f"{inner}termination={condition},")
+    lines.append(f"{indent})")
+    return "\n".join(lines) + "\n"
+
+
+def inference_helper_source() -> str:
+    """The source text emitted as ``signatures/_rote_inference.py``.
+
+    Verbatim, byte for byte — the same contract
+    ``extracted/_rote_mcp.py`` has with :mod:`rote.mcp._runtime_helper`.
+    **Never hand-edit the emitted copy; fix the module and re-emit.**
+    """
+    from rote.inference import _runtime_helper
+
+    return Path(_runtime_helper.__file__).read_text(encoding="utf-8")
+
+
+def write_signature_package(
+    writer: EmitWriter,
+    pipeline: Pipeline,
+    *,
+    anthropic_default_model: str,
+    openai_default_model: str,
+    generated_by: str,
+    regen_command: str,
+    context_note: str,
+) -> dict[str, Path]:
+    """Write the whole ``signatures/`` package for a pipeline's judges.
+
+    Every Python-emitting adapter needs the identical tree — the package
+    marker, one typed module per judge, and the verbatim inference
+    helper they all import — differing only in the identity strings
+    stamped into each module's docstring. Those are parameters; the
+    layout is not, because a runtime that emitted a *different* judge
+    package would be a second implementation of the judge.
+
+    Returns the manifest entries to merge into the adapter's ``written``
+    map. Empty only when nothing in the pipeline needs inference — an
+    ``agent_loop`` pulls the helper in even with no judges, since the
+    loop runs through the same provider resolver.
+    """
+    judges = spec_judges(pipeline)
+    agent_loops = pipeline.nodes_by_kind(NodeKind.AGENT_LOOP)
+    if not judges and not agent_loops:
+        return {}
+    pipeline_name = pipeline.name
+    written: dict[str, Path] = {
+        "signatures/__init__": writer.write(
+            "signatures",
+            "__init__.py",
+            content=f'"""Generated LLM signatures for {pipeline_name}."""\n',
+        ),
+        # The provider resolver is the *source text* of
+        # rote.inference._runtime_helper — one tested implementation,
+        # emitted verbatim so the app stays standalone (no rote import
+        # at runtime) while every judge shares one billing decision.
+        "signatures/_rote_inference": writer.write(
+            "signatures",
+            "_rote_inference.py",
+            content=inference_helper_source(),
+        ),
+    }
+    for node in judges:
+        written[f"signatures/{node.id}"] = writer.write(
+            "signatures",
+            f"{node.id}.py",
+            content=emit_signature_module(
+                node,
+                anthropic_default_model=anthropic_default_model,
+                openai_default_model=openai_default_model,
+                generated_by=generated_by,
+                regen_command=regen_command,
+                context_note=context_note,
+            ),
+        )
+    return written
+
+
+def spec_judges(pipeline: Pipeline) -> list[Node]:
+    """The llm_judge nodes carrying a structured ``signature_spec``."""
+    return [
+        n for n in pipeline.nodes if n.kind is NodeKind.LLM_JUDGE and n.signature_spec is not None
+    ]
 
 
 # ───────── extracted/<module>.py emission ─────────
@@ -743,8 +833,8 @@ def _emit_forward_openai(node: Node, pascal: str, spec: LLMSignature) -> str:
 def resolve_extracted_source(source_dir: Path | None, module_name: str) -> str | None:
     """The agent-written ``extracted/<module>.py`` beside the pipeline, if any.
 
-    A compilation writes its real (test-verified) implementations into
-    ``<compiled>/extracted/`` next to ``pipeline.yaml``. Emission
+    A graduation writes its real (test-verified) implementations into
+    ``<graduated>/extracted/`` next to ``pipeline.yaml``. Emission
     prefers those files verbatim over IR-derived stubs so the runtime
     dir runs without anyone hand-copying modules across — the gap that
     made the first real-server pipeline raise ``NotImplementedError``
@@ -780,8 +870,9 @@ def _extracted_layout(pipeline: Pipeline) -> dict[str, list[Node]]:
                 continue
             module_name, _ = _impl_path_parts(node.impl)
             modules.setdefault(module_name, []).append(node)
-        elif node.kind is NodeKind.AGENT_LOOP:
-            modules.setdefault(node.id, []).append(node)
+        # agent_loop nodes deliberately get no extracted/ module: since
+        # the inference helper runs them as real bounded loops, a stub
+        # would be dead code that only invites someone to fill it in.
     return modules
 
 
@@ -804,7 +895,7 @@ def emit_extracted_module(
 
     Same scaffolding convention as the Temporal example package: the
     functions raise ``NotImplementedError`` until the user fills them in
-    with direct vendor API calls. The compilation history (MCP origin) is
+    with direct vendor API calls. The graduation history (MCP origin) is
     documented in docstrings only — never in executable code.
 
     ``caller_note`` finishes the "Keep the signatures: …" sentence with
@@ -816,7 +907,7 @@ def emit_extracted_module(
 
         Auto-generated stubs by {generated_by}. Replace each body
         with the real implementation (direct vendor API calls — the MCP
-        tool calls from the source skill were compiled away at emit
+        tool calls from the source skill were graduated away at emit
         time). Keep the signatures: {caller_note}
         """