premanmcp 1.1.7 → 1.1.9

package/bin/eval_templates.js

@@ -0,0 +1,684 @@
+/**
+ * The wrapper, assembled here rather than written by a model.
+ *
+ * Discovery used to ask for a complete Python file back. That measured 2/6 on
+ * determinism -- three repositories named the right entry point twice and still
+ * produced different bytes each run -- because a model writing a whole file
+ * freehand has no reason to write it the same way twice. It also limited the
+ * feature to the two languages the prompt happened to explain, since the model
+ * could only produce an invocation it had been told how to write.
+ *
+ * So the model now answers `{entry_file, entry_symbol, shape}` and the CLI owns
+ * the file. For every shape below, no model writes any code, which makes the
+ * output byte-identical across runs and makes a new language a template rather
+ * than a new paragraph of prompt.
+ *
+ * `history` as the parameter name and the `{"response", "events"}` return shape
+ * become structural guarantees here instead of prompt rules checked afterwards
+ * by a probe.
+ */
+
+/** Shapes the CLI can build with no model-written code. */
+export const SHAPES = new Set([
+  "py_history",      // f(message, history)
+  "py_plain",        // f(message)
+  "py_class",        // Class().method(message)
+  "langgraph",       // compiled graph.invoke({"messages": [...]})
+  "node_bridge",     // a JS/TS agent over a long-lived node process
+  "cli_subprocess",  // a compiled or standalone binary, one process per turn
+]);
+
+/** A shape the CLI cannot build: the model supplies one function body. */
+export const FREEFORM = "other";
+
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Python literal for a JS string. JSON is a subset of Python for these. */
+function lit(value) {
+  return JSON.stringify(String(value ?? ""));
+}
+
+/** Python list-of-strings literal. */
+function litList(values) {
+  return `[${(values || []).map((v) => lit(v)).join(", ")}]`;
+}
+
+// ── The parts every wrapper shares ──────────────────────────────────────
+
+const HEADER = `# Generated by \`preman eval target\`. Do not edit by hand.
+# shape: %%SHAPE%%   entry: %%ENTRY_DISPLAY%%
+#
+# Regenerate with \`preman eval target\` rather than editing: the digest in
+# .preman.json is what proves this file is the one that was approved.
+`;
+
+/**
+ * Loading the target module.
+ *
+ * Deliberately lazy -- importing this wrapper must not start a server or open a
+ * socket, because a health probe imports it without wanting to run anything.
+ * `preman_selfcheck` is the explicit way to ask "does this still work here".
+ *
+ * The global is assigned only after `exec_module` returns. Assigning it first
+ * leaves a non-None empty module cached when a load fails, and then every turn
+ * after the first reports `has no attribute <symbol>` instead of the real import
+ * error -- which reads as a bug in the customer's file when the customer's file
+ * is fine.
+ */
+const PY_LOADER = String.raw`
+import importlib.util
+import sys
+from pathlib import Path
+
+_REPO = Path(__file__).resolve().parent.parent
+_SRC = _REPO / %%ENTRY_FILE%%
+_SYMBOL = %%ENTRY_SYMBOL%%
+_mod = None
+
+
+def _agent():
+    global _mod
+    if _mod is None:
+        if str(_REPO) not in sys.path:
+            sys.path.insert(0, str(_REPO))
+        spec = importlib.util.spec_from_file_location("preman_target_agent", _SRC)
+        if spec is None or spec.loader is None:
+            raise ImportError("no import spec for %s" % _SRC)
+        mod = importlib.util.module_from_spec(spec)
+        sys.modules[spec.name] = mod
+        try:
+            spec.loader.exec_module(mod)
+        except BaseException:
+            sys.modules.pop(spec.name, None)
+            raise
+        _mod = mod
+    return _mod
+
+
+def _target():
+    agent = _agent()
+    try:
+        return getattr(agent, _SYMBOL)
+    except AttributeError:
+        names = ", ".join(n for n in dir(agent) if not n.startswith("_"))
+        raise AttributeError(
+            "%s defines no %r. It defines: %s" % (_SRC, _SYMBOL, names)
+        ) from None
+
+
+def preman_selfcheck() -> str:
+    _target()
+    return _SYMBOL
+`;
+
+/**
+ * The reply, normalised.
+ *
+ * Owned by the CLI for every shape: the harness needs a dict with a string
+ * `response`, and an agent that returns a bare string, a dataclass or a
+ * LangGraph state dict is the normal case rather than the exception.
+ */
+const PY_NORMALISE = String.raw`
+
+def _flatten(message, history):
+    """The conversation as one string, for an agent that takes only a message.
+
+    Shared by every shape that cannot pass prior turns through: an agent which
+    is handed only the latest message answers a multi-turn case as though it
+    were the first turn, and the run still exits 0, so the score is wrong and
+    nothing says so.
+    """
+    if not history:
+        return message
+    lines = []
+    for item in history:
+        role = (item or {}).get("role") or "user"
+        speaker = "Assistant" if role == "assistant" else "User"
+        lines.append("%s: %s" % (speaker, (item or {}).get("content", "")))
+    lines.append("User: %s" % message)
+    return "\n\n".join(lines)
+
+
+def _text(value):
+    """Best-effort reply text from whatever the agent returned."""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, dict):
+        for key in ("response", "output", "text", "content", "result", "answer"):
+            found = value.get(key)
+            if isinstance(found, str) and found.strip():
+                return found
+        messages = value.get("messages")
+        if isinstance(messages, list) and messages:
+            last = messages[-1]
+            content = getattr(last, "content", None)
+            if content is None and isinstance(last, dict):
+                content = last.get("content")
+            if isinstance(content, str):
+                return content
+            return str(content)
+    for attr in ("content", "text", "raw", "output"):
+        found = getattr(value, attr, None)
+        if isinstance(found, str) and found.strip():
+            return found
+    return "" if value is None else str(value)
+
+
+def chat(message: str, history: list | None = None) -> dict:
+    reply, events = _turn(message, history or [])
+    return {"response": _text(reply), "events": list(events or [])}
+`;
+
+// ── One `_turn` per shape ───────────────────────────────────────────────
+
+const TURNS = {
+  py_history: String.raw`
+
+def _turn(message, history):
+    return _target()(message, history), []
+`,
+
+  py_plain: String.raw`
+# The agent takes no prior turns, so the conversation is flattened into the
+# message. Dropping it silently would make a multi-turn behaviour score as
+# though the agent had been given context it never saw.
+
+def _turn(message, history):
+    return _target()(_flatten(message, history)), []
+`,
+
+  py_class: String.raw`
+# The symbol is a class: constructed once and reused, so per-turn state the
+# agent keeps for itself survives the conversation.
+#
+# Whether the method accepts prior turns is decided by reading its signature,
+# ONCE, not by calling it and catching TypeError. Two reasons, both measured:
+# a TypeError raised from inside the method body is indistinguishable from an
+# arity mismatch, so the retry ran the agent twice for one turn -- real provider
+# spend and duplicated side effects; and the old fallback called method(message)
+# with no flattening, so a stateless class silently never saw the conversation
+# and a multi-turn case scored as though it had.
+import inspect
+
+_instance = None
+_takes_history = None
+
+
+def _turn(message, history):
+    global _instance, _takes_history
+    if _instance is None:
+        _instance = _target()()
+    method = getattr(_instance, %%METHOD%%)
+    if _takes_history is None:
+        try:
+            params = list(inspect.signature(method).parameters.values())
+        except (TypeError, ValueError):
+            # A C-implemented or otherwise unintrospectable callable. Assume the
+            # narrower signature and flatten, which is wrong-but-complete rather
+            # than wrong-and-silently-missing-the-conversation.
+            _takes_history = False
+        else:
+            _takes_history = len(params) >= 2 or any(
+                p.kind in (p.VAR_POSITIONAL, p.VAR_KEYWORD) for p in params
+            )
+    if _takes_history:
+        return method(message, history), []
+    return method(_flatten(message, history)), []
+`,
+
+  langgraph: String.raw`
+# A compiled graph: invoked with the whole conversation, because a graph holds
+# no state between invocations and re-sending the transcript is how it sees one.
+#
+# Messages go in as OBJECTS, not as {"role", "content"} dicts. A graph node is
+# normally written against LangChain messages and reads \`m.content\` and
+# \`m.type\`, which a dict does not have -- measured: passing dicts broke a
+# fixture whose reference wrapper passed objects. The fallback below carries
+# both shapes at once so a node written either way works.
+try:
+    from langchain_core.messages import AIMessage, HumanMessage
+
+    def _msg(role, content):
+        return AIMessage(content) if role == "assistant" else HumanMessage(content)
+
+except Exception:
+
+    class _Msg(dict):
+        def __init__(self, role, content):
+            super().__init__(role=role, content=content)
+            self.content = content
+            self.type = "ai" if role == "assistant" else "human"
+
+    def _msg(role, content):
+        return _Msg(role, content)
+
+
+def _turn(message, history):
+    messages = []
+    for item in history:
+        role = (item or {}).get("role") or "user"
+        messages.append(_msg(role, (item or {}).get("content", "")))
+    messages.append(_msg("user", message))
+    state = _target().invoke({"messages": messages})
+    return state, []
+`,
+};
+
+// ── Shapes that are not a Python import at all ──────────────────────────
+
+/**
+ * A JS/TS agent, over one long-lived node process.
+ *
+ * The protocol lives here rather than in the prompt. It used to be a paragraph
+ * the model retyped every run, and that is the one fixture the measured baseline
+ * failed: the reference bridge passed on the same machine while the generated
+ * one did not.
+ *
+ * stdout carries the protocol, so the child's own logging has to go to stderr or
+ * the first `console.log` in the agent corrupts a reply.
+ */
+const NODE_BRIDGE = String.raw`
+import json
+import shutil
+import subprocess
+import threading
+
+_REPO = Path(__file__).resolve().parent.parent
+_BRIDGE = Path(__file__).resolve().parent / "agent_bridge.mjs"
+# The child's stderr goes to a file rather than being inherited, so that when the
+# bridge dies its reason can be quoted back. Inheriting it printed a perfectly
+# clear ERR_MODULE_NOT_FOUND somewhere the caller never looked, and the wrapper
+# reported only "closed without answering" -- true, and no use to anybody.
+_STDERR = Path(__file__).resolve().parent / "agent_bridge.log"
+_WANTED = %%NODE_RUNTIME%%
+_proc = None
+_lock = threading.Lock()
+
+
+def _why() -> str:
+    """Why the bridge stopped, taken from the most informative line it wrote.
+
+    The FIRST Error line, not the tail: a Node crash prints its message near the
+    top and then a stack and a version footer, so quoting the end of the output
+    reliably captures the least useful part of it.
+    """
+    try:
+        text = _STDERR.read_text(errors="replace").strip()
+    except OSError:
+        return ""
+    if not text:
+        return ""
+    for line in text.splitlines():
+        stripped = line.strip()
+        if "Error" in stripped and len(stripped) > 12:
+            return ": " + stripped[:600]
+    return ": " + text[:600]
+
+
+def _runtime() -> str:
+    """The runtime that is actually installed, preferring the one named.
+
+    "tsx" and "ts-node" are the obvious answers for a .ts entry point and are
+    frequently absent -- measured: a discovery run named "tsx", it was not on
+    PATH, and the wrapper died inside subprocess with a FileNotFoundError that
+    read as a broken wrapper rather than a missing tool. Current Node strips
+    TypeScript types by itself, so falling back to "node" is usually right and
+    is always better than a traceback.
+    """
+    for name in (_WANTED, "node"):
+        if name and shutil.which(name):
+            return name
+    raise RuntimeError(
+        "no JavaScript runtime found: tried %r and 'node'. Install Node, or "
+        "put %r on PATH." % (_WANTED, _WANTED)
+    )
+
+
+def _bridge():
+    global _proc
+    if _proc is None or _proc.poll() is not None:
+        _proc = subprocess.Popen(
+            [_runtime(), str(_BRIDGE)],
+            cwd=str(_REPO),
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=open(_STDERR, "w"),
+            text=True,
+            bufsize=1,
+        )
+    return _proc
+
+
+def preman_selfcheck() -> str:
+    _runtime()
+    proc = _bridge()
+    if proc.poll() is not None:
+        raise RuntimeError(
+            "the node bridge exited with %s%s" % (proc.returncode, _why())
+        )
+    return %%ENTRY_SYMBOL%%
+
+
+def _turn(message, history):
+    with _lock:
+        proc = _bridge()
+        proc.stdin.write(json.dumps({"message": message, "history": history}) + "\n")
+        proc.stdin.flush()
+        line = proc.stdout.readline()
+        if not line:
+            raise RuntimeError("the node bridge closed without answering%s" % _why())
+        parsed = json.loads(line)
+        if parsed.get("error"):
+            raise RuntimeError(str(parsed["error"]))
+        return parsed.get("response", ""), parsed.get("events", [])
+`;
+
+/** The node side. Also CLI-owned, for the same reason. */
+const NODE_SIDE = String.raw`// Generated by `+"`preman eval target`"+String.raw`. Do not edit by hand.
+//
+// One JSON object per line in, one per line out. stdout is the protocol, so
+// anything the agent prints is redirected to stderr before it can corrupt a
+// reply.
+import { createInterface } from "node:readline";
+
+const out = process.stdout.write.bind(process.stdout);
+console.log = (...args) => process.stderr.write(args.join(" ") + "\n");
+
+const mod = await import(%%NODE_ENTRY%%);
+const agent = mod[%%ENTRY_SYMBOL%%] ?? mod.default;
+if (typeof agent !== "function") {
+  out(JSON.stringify({ error: %%ENTRY_SYMBOL%% + " is not a function in " + %%NODE_ENTRY%% }) + "\n");
+  process.exit(1);
+}
+
+for await (const line of createInterface({ input: process.stdin })) {
+  if (!line.trim()) continue;
+  try {
+    const { message, history } = JSON.parse(line);
+    const reply = await agent(message, history ?? []);
+    const text = typeof reply === "string" ? reply : (reply?.response ?? JSON.stringify(reply));
+    out(JSON.stringify({ response: text, events: reply?.events ?? [] }) + "\n");
+  } catch (error) {
+    out(JSON.stringify({ error: String(error?.stack || error) }) + "\n");
+  }
+}
+`;
+
+/**
+ * A compiled or standalone binary: one process per turn.
+ *
+ * This is what makes a language other than Python or JavaScript reachable at
+ * all. The agent is not imported, so nothing about it has to be Python -- Rust,
+ * Go, Java, Ruby and any CLI-shaped agent use this one template.
+ *
+ * One process per turn rather than a long-lived one: a CLI agent generally
+ * starts a fresh session per invocation, so prior turns are replayed as text.
+ * That is lossy and costs tokens quadratically, but it is repeatable, and an
+ * eval that is not repeatable is not measuring anything.
+ *
+ * The prompt goes on stdin, never argv: argv needs quoting, has a length limit,
+ * and shows up in process listings.
+ */
+const CLI_SUBPROCESS = String.raw`
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+_REPO = Path(__file__).resolve().parent.parent
+_ARGV = %%COMMAND%%
+_TIMEOUT = float(os.environ.get("PREMAN_AGENT_TIMEOUT", "300"))
+
+
+def _binary() -> str:
+    """The executable, with the repository's own build output preferred."""
+    override = os.environ.get("PREMAN_AGENT_BIN")
+    if override:
+        if not Path(override).is_file():
+            raise RuntimeError("PREMAN_AGENT_BIN=%s is not a file" % override)
+        return override
+    name = _ARGV[0]
+    candidate = _REPO / name
+    if candidate.is_file():
+        return str(candidate)
+    for folder in ("target/release", "target/debug", "bin", "build", "dist"):
+        candidate = _REPO / folder / Path(name).name
+        if candidate.is_file():
+            return str(candidate)
+    found = shutil.which(name)
+    if found:
+        return found
+    raise RuntimeError(
+        "no %r executable found. Build it, put it on PATH, or set "
+        "PREMAN_AGENT_BIN to the one to use." % name
+    )
+
+
+#: Extensions worth comparing a build against. Deliberately not every file --
+#: a README newer than the binary says nothing about whether it is stale.
+_SOURCE_SUFFIXES = (
+    ".rs", ".go", ".java", ".kt", ".rb", ".cs", ".ex", ".exs", ".php",
+    ".swift", ".c", ".h", ".cc", ".cpp", ".hpp", ".m", ".mm", ".zig",
+)
+
+_SKIP_DIRS = {
+    ".git", "target", "build", "dist", "bin", "vendor", "node_modules",
+    ".preman", "__pycache__",
+}
+
+
+def _staleness(binary: str) -> str:
+    """"" if the build looks current, else a sentence naming the newer file.
+
+    A binary that answers happily while being older than the code is the worst
+    outcome available here: the probe passes, the run completes, and the score
+    describes software that no longer exists. Nothing on disk links a binary to
+    the source it was built from, so the timestamp is the only evidence there
+    is -- weak, and much better than nothing.
+    """
+    try:
+        built = Path(binary).stat().st_mtime
+    except OSError:
+        return ""
+    newest, newest_at = None, built
+    for path in _REPO.rglob("*"):
+        if path.suffix not in _SOURCE_SUFFIXES:
+            continue
+        if any(part in _SKIP_DIRS for part in path.parts):
+            continue
+        try:
+            when = path.stat().st_mtime
+        except OSError:
+            continue
+        if when > newest_at:
+            newest, newest_at = path, when
+    # A couple of minutes of slack. A build followed immediately by a formatter,
+    # a recursive copy of the tree, or a checkout that stamps every file the same
+    # time are all normal and none of them mean the binary is out of date --
+    # warning about them would train the reader to ignore the warning.
+    if newest is None or (newest_at - built) < 120:
+        return ""
+    ago = (newest_at - built) / 3600.0
+    return (
+        "%s was modified %.1f hours after %s was built, so this binary may not "
+        "be the code you are measuring. Rebuild it, or set PREMAN_AGENT_BIN."
+        % (newest.relative_to(_REPO), ago, Path(binary).name)
+    )
+
+
+def preman_selfcheck() -> str:
+    """The resolved path, not the name that was typed.
+
+    A caller approving "mytool exec -" cannot otherwise tell whether that found
+    the repository's own build output or an unrelated mytool on PATH, and the
+    two produce equally confident answers.
+    """
+    binary = _binary()
+    stale = _staleness(binary)
+    return binary + ("  [STALE] " + stale if stale else "")
+
+
+def _prompt(message, history):
+    if not history:
+        return message
+    lines = []
+    for item in history:
+        role = (item or {}).get("role") or "user"
+        speaker = "Assistant" if role == "assistant" else "User"
+        lines.append("%s: %s" % (speaker, (item or {}).get("content", "")))
+    lines.append("User: %s" % message)
+    return "\n\n".join(lines)
+
+
+def _turn(message, history):
+    argv = [_binary()] + list(_ARGV[1:])
+    done = subprocess.run(
+        argv,
+        input=_prompt(message, history),
+        capture_output=True,
+        text=True,
+        cwd=str(_REPO),
+        timeout=_TIMEOUT,
+    )
+    if done.returncode != 0:
+        tail = (done.stderr or "").strip()[-600:]
+        raise RuntimeError("%s exited %s: %s" % (_ARGV[0], done.returncode, tail))
+    return done.stdout.strip(), []
+`;
+
+// ── Assembly ────────────────────────────────────────────────────────────
+
+export class TemplateError extends Error {}
+
+/**
+ * The wrapper for one answer, or a TemplateError naming what was unusable.
+ *
+ * Every value the model supplied is checked before it reaches a template:
+ * `entry_file` must be a member of the tree it was shown, symbols must be
+ * identifiers, and a command must be a non-empty argv. An unchecked value here
+ * would be a model writing code by choosing a string.
+ */
+export function buildWrapper(found, { tree = [] } = {}) {
+  const shape = String(found?.shape || "");
+  if (!SHAPES.has(shape)) {
+    throw new TemplateError(`unknown shape ${JSON.stringify(shape)}`);
+  }
+
+  const entryFile = String(found?.entry_file || "");
+  if (shape !== "cli_subprocess") {
+    if (!entryFile) throw new TemplateError("no entry_file");
+    if (tree.length && !tree.includes(entryFile)) {
+      throw new TemplateError(`entry_file ${entryFile} is not in this repository`);
+    }
+  }
+
+  const symbol = String(found?.entry_symbol || "");
+  const needsSymbol = shape !== "cli_subprocess";
+  if (needsSymbol && !IDENT.test(symbol)) {
+    throw new TemplateError(`entry_symbol ${JSON.stringify(symbol)} is not an identifier`);
+  }
+
+  // Checked before anything interpolates it. Building the header first meant a
+  // `command` that was a string rather than an argv threw a raw TypeError out
+  // of `.join`, and the caller only catches TemplateError -- so a bad value
+  // surfaced as a crash instead of "PreMan could not build a wrapper".
+  let command = null;
+  if (shape === "cli_subprocess") {
+    command = Array.isArray(found?.command) ? found.command.map(String) : [];
+    if (!command.length || !command[0].trim()) {
+      throw new TemplateError("cli_subprocess needs a command, e.g. [\"mytool\", \"--json\", \"-\"]");
+    }
+  }
+
+  const header = HEADER
+    .replace("%%SHAPE%%", shape)
+    .replace("%%ENTRY_DISPLAY%%", command ? command.join(" ") : `${entryFile}:${symbol}`);
+
+  if (shape === "cli_subprocess") {
+    return {
+      shim: header + CLI_SUBPROCESS.replace("%%COMMAND%%", litList(command)) + PY_NORMALISE,
+      bridge: "",
+    };
+  }
+
+  if (shape === "node_bridge") {
+    const runtime = String(found?.node_runtime || "node");
+    if (!["node", "tsx", "ts-node"].includes(runtime)) {
+      throw new TemplateError(`node_runtime ${JSON.stringify(runtime)} is not one we can run`);
+    }
+    const nodeEntry = String(found?.node_entry || entryFile);
+    if (tree.length && !tree.includes(nodeEntry)) {
+      throw new TemplateError(`node_entry ${nodeEntry} is not in this repository`);
+    }
+    const shim = header
+      + "from pathlib import Path\n"
+      + NODE_BRIDGE
+          .replace("%%NODE_RUNTIME%%", lit(runtime))
+          .replace("%%ENTRY_SYMBOL%%", lit(symbol))
+      + PY_NORMALISE;
+    const bridge = NODE_SIDE
+      .replace(/%%NODE_ENTRY%%/g, lit("../" + nodeEntry))
+      .replace(/%%ENTRY_SYMBOL%%/g, lit(symbol));
+    return { shim, bridge };
+  }
+
+  let turn = TURNS[shape];
+  if (shape === "py_class") {
+    const method = String(found?.entry_method || "run");
+    if (!IDENT.test(method)) {
+      throw new TemplateError(`entry_method ${JSON.stringify(method)} is not an identifier`);
+    }
+    turn = turn.replace("%%METHOD%%", lit(method));
+  }
+
+  const shim = header
+    + PY_LOADER
+        .replace("%%ENTRY_FILE%%", lit(entryFile))
+        .replace("%%ENTRY_SYMBOL%%", lit(symbol))
+    + turn
+    + PY_NORMALISE;
+  return { shim, bridge: "" };
+}
+
+/**
+ * The `other` shape: the CLI still owns everything except one function body.
+ *
+ * Even here the model writes far less than it used to -- no imports, no module
+ * cache, no reply normalisation, no `chat` signature. Only the conversion from
+ * this agent's calling convention to `(reply, events)`, which is the part that
+ * genuinely varies and the part no template can know.
+ */
+export function buildFreeform(found, { tree = [], turnSource = "" } = {}) {
+  const entryFile = String(found?.entry_file || "");
+  if (!entryFile) throw new TemplateError("no entry_file");
+  if (tree.length && !tree.includes(entryFile)) {
+    throw new TemplateError(`entry_file ${entryFile} is not in this repository`);
+  }
+  const symbol = String(found?.entry_symbol || "");
+  if (!IDENT.test(symbol)) {
+    throw new TemplateError(`entry_symbol ${JSON.stringify(symbol)} is not an identifier`);
+  }
+  const body = String(turnSource || "").trimEnd();
+  if (!body.trim()) throw new TemplateError("no conversion body was returned");
+
+  const header = HEADER
+    .replace("%%SHAPE%%", "other")
+    .replace("%%ENTRY_DISPLAY%%", `${entryFile}:${symbol}`);
+  // The symbol is bound by its own name before the model's body runs.
+  //
+  // Measured: a real answer for a CrewAI repository wrote
+  // `Testcrew().crew().kickoff(...)`, which is the natural thing to write and
+  // failed with `NameError: name 'Testcrew' is not defined` -- the loader
+  // exposes `_target()`, and nothing told the model that. Binding the name here
+  // means the obvious body works, and the prompt now says so as well; either
+  // alone would leave the other as a trap.
+  const shim = header
+    + PY_LOADER
+        .replace("%%ENTRY_FILE%%", lit(entryFile))
+        .replace("%%ENTRY_SYMBOL%%", lit(symbol))
+    + "\n\ndef _turn(message, history):\n"
+    + `    ${symbol} = _target()\n`
+    + body + "\n"
+    + PY_NORMALISE;
+  return { shim, bridge: "" };
+}