premanmcp 1.1.13 → 1.1.15

package/bin/decorate_tools.py

@@ -0,0 +1,368 @@
+"""Plan the edit that puts @preman_tool on an agent's tool functions.
+
+Run by `preman eval target` as
+
+    uv run --no-project --with libcst python decorate_tools.py --repo ROOT --plan PLAN.json
+
+PLAN.json is {"tools": [{"file", "symbol", "tool_name"}]}. Prints one JSON
+object on stdout and never writes a file: the CLI shows the diff, asks, and
+writes. The same plan on the same files always gives the same bytes
+(docs/superpowers/specs/2026-10-04-tool-decorators-design.md §6.1).
+
+Nothing is added to the customer's dependencies: each edited file gets a
+guarded import whose fallback decorates with nothing, so the code runs
+unchanged wherever PreMan's recorder is not importable (everywhere but an eval).
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+import libcst as cst
+import libcst.matchers as m
+
+SKIP_DIRS = {
+    "node_modules", ".venv", "venv", ".git", "dist", "build", "__pycache__",
+    ".next", ".turbo", "target", ".mypy_cache", ".pytest_cache", ".preman",
+}
+NAME_SUFFIXES = {".py", ".json", ".yaml", ".yml", ".toml"}
+MAX_SCAN_BYTES = 1_000_000
+
+GUARD = (
+    "try:\n"
+    "    from preman import tool as preman_tool\n"
+    "except ImportError:  # PreMan's eval recorder; without it, decorate with nothing\n"
+    "    def preman_tool(name):\n"
+    "        return lambda fn: fn\n"
+)
+GUARD_IMPORT = "from preman import tool as preman_tool"
+
+# Framework tool decorators whose tracing plugin, installed for the eval,
+# already records every call. Decorating them too counts each call twice
+# (spec §4.4), so these are left alone and recorded by the plugin.
+COVERED = {
+    ("langchain_core.tools", "tool"): "langchain",
+    ("langchain.tools", "tool"): "langchain",
+    ("langchain.agents", "tool"): "langchain",
+}
+# Framework tools whose plugin may or may not record them: unverified, so
+# neither decorated (possible double count) nor trusted to the plugin.
+UNSUPPORTED = {
+    ("agents", "function_tool"): "OpenAI Agents SDK tools are not supported yet",
+}
+# Wrappers that call the function they wrap and return a plain function.
+# @preman_tool may sit above these. Every other decorator may register the
+# function it receives (@agent.tool, @mcp.tool()) or turn it into an object
+# (@property, CrewAI's @tool), so @preman_tool goes beneath the lowest of
+# those: what the framework holds is then the recorded function.
+PASS_THROUGH = {
+    ("functools", "lru_cache"), ("functools", "cache"), ("tenacity", "retry"),
+    ("backoff", "on_exception"), ("backoff", "on_predicate"),
+}
+# What an existing PreMan decorator resolves to: the guard's name, or a
+# hand-written `import preman` + `@preman.tool`.
+PREMAN = {("", "preman_tool"), ("preman", "tool")}
+# Valid tool names: alphanumeric, hyphen, underscore, 1-64 chars.
+TOOL_NAME_PATTERN = re.compile(r"[A-Za-z0-9_-]{1,64}")
+
+
+def _dotted(node) -> str:
+    if isinstance(node, cst.Name):
+        return node.value
+    if isinstance(node, cst.Attribute):
+        head = _dotted(node.value)
+        return "%s.%s" % (head, node.attr.value) if head else ""
+    return ""
+
+
+def _imports(module: cst.Module) -> dict[str, str]:
+    """Local name -> what it refers to, e.g. {"tool": "langchain_core.tools.tool", "lt": "langchain_core.tools"}."""
+    names: dict[str, str] = {}
+    for stmt in module.body:
+        if not isinstance(stmt, cst.SimpleStatementLine):
+            continue
+        for small in stmt.body:
+            if isinstance(small, cst.ImportFrom) and small.module is not None and not small.relative:
+                if isinstance(small.names, cst.ImportStar):
+                    continue
+                base = _dotted(small.module)
+                for alias in small.names:
+                    local = alias.asname.name.value if alias.asname else _dotted(alias.name)
+                    names[local] = "%s.%s" % (base, _dotted(alias.name))
+            elif isinstance(small, cst.Import):
+                for alias in small.names:
+                    full = _dotted(alias.name)
+                    local = alias.asname.name.value if alias.asname else full.split(".")[0]
+                    names[local] = full if alias.asname else local
+    return names
+
+
+def _resolve(expr, imports: dict[str, str]) -> tuple[str, str]:
+    """(module, name) a decorator expression refers to; ("", name) for an unimported bare name."""
+    if isinstance(expr, cst.Call):
+        expr = expr.func
+    dotted = _dotted(expr)
+    if not dotted:
+        return "", ""
+    head, _, rest = dotted.partition(".")
+    full = imports.get(head, head)
+    full = "%s.%s" % (full, rest) if rest else full
+    module, _, name = full.rpartition(".")
+    return module, name
+
+
+def _string_arg(expr) -> str:
+    if isinstance(expr, cst.Call) and expr.args and isinstance(expr.args[0].value, cst.SimpleString):
+        return expr.args[0].value.evaluated_value
+    return ""
+
+
+class _Yields(cst.CSTVisitor):
+    def __init__(self):
+        self.found = False
+
+    def visit_FunctionDef(self, node):
+        return False
+
+    def visit_Lambda(self, node):
+        return False
+
+    def visit_Yield(self, node):
+        self.found = True
+
+
+def _is_generator(fn: cst.FunctionDef) -> bool:
+    visitor = _Yields()
+    fn.body.visit(visitor)
+    return visitor.found
+
+
+def _from_function_refs(module: cst.Module) -> dict[str, tuple[str, str]]:
+    """Functions handed to a framework's tool factory: name -> (kind, framework or reason)."""
+    refs: dict[str, tuple[str, str]] = {}
+
+    class Calls(cst.CSTVisitor):
+        def visit_Call(self, node):
+            if not isinstance(node.func, cst.Attribute):
+                return
+            attr = node.func.attr.value
+            for arg in node.args:
+                if not isinstance(arg.value, cst.Name):
+                    continue
+                keyword = arg.keyword.value if arg.keyword else ""
+                if attr == "from_function" and keyword in ("", "func"):
+                    refs.setdefault(arg.value.value, ("covered", "langchain"))
+                elif attr == "from_defaults" and keyword in ("", "fn"):
+                    refs.setdefault(arg.value.value, ("dropped", "LlamaIndex tools are not supported yet"))
+
+    module.visit(Calls())
+    return refs
+
+
+class _Decorate(cst.CSTTransformer):
+    """Adds @preman_tool to the wanted functions and records an outcome for each."""
+
+    def __init__(self, wanted, imports, factory_refs, name_ok):
+        self.wanted = wanted              # {(class or "", function): tool_name}
+        self.imports = imports
+        self.factory_refs = factory_refs
+        self.name_ok = name_ok
+        self.classes: list[str] = []
+        self.depth = 0
+        self.outcomes: dict[tuple[str, str], tuple[str, str]] = {}
+        self.added = False
+
+    def _outcome(self, key, kind, detail):
+        # A symbol defined more than once (if/else, try/except, a redefinition)
+        # is edited at every definition and reported once; any definition that
+        # is not decorated decides the report.
+        if self.outcomes.get(key, ("decorate", ""))[0] == "decorate":
+            self.outcomes[key] = (kind, detail)
+
+    def visit_ClassDef(self, node):
+        self.classes.append(node.name.value)
+
+    def leave_ClassDef(self, original, updated):
+        self.classes.pop()
+        return updated
+
+    def visit_FunctionDef(self, node):
+        self.depth += 1
+
+    def leave_FunctionDef(self, original, updated):
+        self.depth -= 1
+        if self.depth != 0 or len(self.classes) > 1:
+            return updated
+        key = (self.classes[0] if self.classes else "", original.name.value)
+        if key not in self.wanted:
+            return updated
+        tool_name = self.wanted[key]
+        resolved = [_resolve(d.decorator, self.imports) for d in original.decorators]
+        for d, where in zip(original.decorators, resolved):
+            if where in PREMAN:
+                existing = _string_arg(d.decorator)
+                if existing == tool_name:
+                    self._outcome(key, "decorate", "")
+                else:
+                    self._outcome(key, "dropped", 'already decorated as @preman_tool("%s")' % existing)
+                return updated
+        for where in resolved:
+            if where in COVERED:
+                self._outcome(key, "covered", COVERED[where])
+                return updated
+            if where in UNSUPPORTED:
+                self._outcome(key, "dropped", UNSUPPORTED[where])
+                return updated
+        if not key[0] and key[1] in self.factory_refs:
+            self._outcome(key, *self.factory_refs[key[1]])
+            return updated
+        if _is_generator(original):
+            self._outcome(key, "dropped", "a generator function, which preman_tool cannot record")
+            return updated
+        if not self.name_ok(tool_name):
+            self._outcome(key, "dropped", 'the tool name "%s" was not found as a string anywhere in the repository' % tool_name)
+            return updated
+        deco = cst.Decorator(decorator=cst.parse_expression("preman_tool(%s)" % json.dumps(tool_name)))
+        at = 0
+        for i, where in enumerate(resolved):
+            if where not in PASS_THROUGH:
+                at = i + 1
+        decorators = list(updated.decorators)
+        decorators.insert(at, deco)
+        self._outcome(key, "decorate", "")
+        self.added = True
+        return updated.with_changes(decorators=decorators)
+
+
+def _has_guard(module: cst.Module) -> bool:
+    return any(
+        isinstance(stmt, cst.Try) and GUARD_IMPORT in module.code_for_node(stmt)
+        for stmt in module.body
+    )
+
+
+def _with_guard(module: cst.Module) -> cst.Module:
+    body = list(module.body)
+    i = 0
+    if body and m.matches(body[0], m.SimpleStatementLine(body=[m.Expr(m.SimpleString() | m.ConcatenatedString())])):
+        i = 1
+    while i < len(body) and m.matches(body[i], m.SimpleStatementLine(body=[m.ImportFrom(module=m.Name("__future__"))])):
+        i += 1
+    if i < len(body) and not body[i].leading_lines:
+        body[i] = body[i].with_changes(leading_lines=[cst.EmptyLine()])
+    body.insert(i, cst.parse_module(GUARD).body[0])
+    return module.with_changes(body=body)
+
+
+def _name_blob(repo: Path) -> str:
+    parts = []
+    for dirpath, dirnames, filenames in os.walk(repo):
+        dirnames[:] = sorted(d for d in dirnames if d not in SKIP_DIRS and not d.startswith("."))
+        for name in sorted(filenames):
+            path = Path(dirpath) / name
+            if path.suffix not in NAME_SUFFIXES:
+                continue
+            try:
+                if path.stat().st_size <= MAX_SCAN_BYTES:
+                    parts.append(path.read_text(encoding="utf-8", errors="ignore"))
+            except OSError:
+                continue
+    return "\n".join(parts)
+
+
+def plan(repo: Path, tools: list[dict]) -> dict:
+    repo_resolved = repo.resolve()
+    by_file: dict[str, list[dict]] = {}
+    decorate, covered, dropped, files = [], [], [], []
+    blob: list[str] = []
+    # Validate tool_names first and separate valid from invalid
+    for t in tools:
+        name = t.get("tool_name")
+        if not isinstance(name, str) or not TOOL_NAME_PATTERN.fullmatch(name):
+            dropped.append({**t, "why": 'the tool name "%s" is not a tool name' % name})
+        else:
+            by_file.setdefault(str(t["file"]), []).append(t)
+
+    def name_ok(name: str) -> bool:
+        if not blob:
+            blob.append(_name_blob(repo))
+        return '"%s"' % name in blob[0] or "'%s'" % name in blob[0]
+
+    for file in sorted(by_file):
+        entries = sorted(by_file[file], key=lambda t: t["symbol"])
+        # Check for absolute paths, ".." segments, and ensure the file is inside the repo
+        file_path_obj = Path(file)
+        if file_path_obj.is_absolute() or ".." in file_path_obj.parts:
+            dropped += [{**t, "why": "%s is outside the repository" % file} for t in entries]
+            continue
+        path = (repo_resolved / file).resolve()
+        if not path.is_relative_to(repo_resolved):
+            dropped += [{**t, "why": "%s is outside the repository" % file} for t in entries]
+            continue
+        if not path.is_file():
+            dropped += [{**t, "why": "%s does not exist" % file} for t in entries]
+            continue
+        try:
+            with open(path, encoding="utf-8", newline="") as f:
+                before = f.read()
+        except UnicodeDecodeError:
+            dropped += [{**t, "why": "%s is not valid UTF-8" % file} for t in entries]
+            continue
+        try:
+            module = cst.parse_module(before)
+        except cst.ParserSyntaxError:
+            dropped += [{**t, "why": "%s does not parse as Python" % file} for t in entries]
+            continue
+        wanted = {}
+        for t in entries:
+            cls, _, fn = t["symbol"].rpartition(".")
+            wanted[(cls, fn)] = t["tool_name"]
+        transformer = _Decorate(wanted, _imports(module), _from_function_refs(module), name_ok)
+        edited = module.visit(transformer)
+        if transformer.added and not _has_guard(edited):
+            edited = _with_guard(edited)
+        for t in entries:
+            cls, _, fn = t["symbol"].rpartition(".")
+            kind, detail = transformer.outcomes.get((cls, fn), ("dropped", "%s is not defined in %s" % (t["symbol"], file)))
+            if kind == "decorate":
+                decorate.append(dict(t))
+            elif kind == "covered":
+                covered.append({**t, "covered_by": detail})
+            else:
+                dropped.append({**t, "why": detail})
+        if edited.code != before:
+            files.append({"path": file, "before": before, "after": edited.code})
+
+    diff = "".join(
+        "".join(difflib.unified_diff(
+            f["before"].splitlines(True), f["after"].splitlines(True),
+            "a/%s" % f["path"], "b/%s" % f["path"],
+        ))
+        for f in files
+    )
+    return {"ok": True, "files": files, "diff": diff, "decorate": decorate,
+            "covered": covered, "dropped": dropped}
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--repo", required=True)
+    parser.add_argument("--plan", required=True)
+    args = parser.parse_args(argv)
+    try:
+        spec = json.loads(Path(args.plan).read_text(encoding="utf-8"))
+        result = plan(Path(args.repo).resolve(), list(spec.get("tools") or []))
+    except (ValueError, KeyError, OSError, TypeError) as exc:
+        result = {"ok": False, "why": "%s: %s" % (type(exc).__name__, exc)}
+    print(json.dumps(result, ensure_ascii=True, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/bin/eval.js

@@ -966,6 +966,9 @@ export function entryImportFailure(python, sysPath, { timeoutMs = 120_000, log =
 
   const snippet = [
     `import sys`,
+    // The CLI's own bin/, where PreMan's recorder (`preman`) lives, as the
+    // harness puts it on the path for itself.
+    `sys.path.insert(0,${JSON.stringify(path.dirname(HARNESS_PATH))})`,
     `sys.path.insert(0,${JSON.stringify(sysPath)})`,
     `import ${CALLABLE_MODULE} as _w`,
     `_c=getattr(_w,"preman_selfcheck",None)`,

package/bin/eval_entry.js

@@ -22,9 +22,11 @@
 
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
 
 import { callBackendJson, cliInvocation, resolveApiKey } from "./shared.js";
 import { REPO_CONFIG, findConfigRoot, findRepoRoot, saveEntry } from "./target.js";
@@ -553,7 +555,7 @@ function ignoreEntryDir(root) {
   return true;
 }
 
-function record(found, file, root, source, { language, alsoWrote = [] }) {
+function record(found, file, root, source, { language, alsoWrote = [], edited = [] }) {
   const sha256 = createHash("sha256").update(source).digest("hex");
   // Hashed from disk rather than from what was generated: the point of the
   // record is to notice a later edit, and a person offered `[e]dit it first`
@@ -566,12 +568,21 @@ function record(found, file, root, source, { language, alsoWrote = [] }) {
       sha256: createHash("sha256").update(readFileSync(extra, "utf8")).digest("hex"),
     });
   }
+  // The customer's own files that carry @preman_tool. Fingerprinted so an edit
+  // to them sends the next run back through review: a tool added or renamed
+  // since approval would otherwise run undecorated and read as zero calls.
+  for (const rel of edited) {
+    const full = path.join(root, rel);
+    if (!existsSync(full)) continue;
+    files.push({ path: rel, sha256: createHash("sha256").update(readFileSync(full, "utf8")).digest("hex") });
+  }
   const entry = {
     file: path.relative(root, file).split(path.sep).join("/"),
     ref: ENTRY_REF,
     sysPath: ENTRY_DIR,
     sha256,
     files,
+    tools: Array.isArray(found.tools) ? found.tools : [],
     // How the wrapper was built. Recorded because it is the one fact that
     // explains the file's contents later: "this came from the langgraph
     // template" is a different thing to debug than "a model wrote this".
@@ -616,7 +627,10 @@ export async function searchForEntry({ projectPath, args, log = () => {} }) {
     );
   }
 
-  return installShim(found, wrapperFor(found, tree), { projectPath, args, log });
+  const decorated = await applyDecorations(found, { root, log });
+  return installShim(decorated.found, wrapperFor(decorated.found, tree), {
+    projectPath, args, log, edited: decorated.edited,
+  });
 }
 
 /**
@@ -683,7 +697,10 @@ export async function entryFromNamedSymbol(named, { projectPath, args, log = ()
         (found?.reasoning ? `\n\nIt said: ${found.reasoning}` : "")
     );
   }
-  return installShim(found, wrapperFor(found, [rel]), { projectPath, args, log });
+  const decorated = await applyDecorations(found, { root, log });
+  return installShim(decorated.found, wrapperFor(decorated.found, [rel]), {
+    projectPath, args, log, edited: decorated.edited,
+  });
 }
 
 /**
@@ -727,7 +744,118 @@ function wrapperFor(found, tree) {
   }
 }
 
-async function installShim(found, built, { projectPath, args, log }) {
+// ── Adding @preman_tool ─────────────────────────────────────────────────
+
+const DECORATE_SCRIPT = fileURLToPath(new URL("./decorate_tools.py", import.meta.url));
+const DECORATE_TIMEOUT_MS = 300_000; // a cold machine downloads libcst
+/** Shapes whose wrapper reads @preman_tool (PY_DECORATED in eval_templates.js). */
+const DECORATED_SHAPES = new Set(["py_history", "py_plain", "py_class", "other"]);
+
+function planDecorations(found, root) {
+  const dir = mkdtempSync(path.join(os.tmpdir(), "preman-decorate-"));
+  try {
+    const planFile = path.join(dir, "plan.json");
+    writeFileSync(planFile, JSON.stringify({ tools: found.tools || [] }), "utf8");
+    const ran = spawnSync(
+      "uv",
+      ["run", "--no-project", "--with", "libcst", "python", DECORATE_SCRIPT, "--repo", root, "--plan", planFile],
+      { encoding: "utf8", timeout: DECORATE_TIMEOUT_MS }
+    );
+    if (ran.error?.code === "ENOENT") {
+      throw new TargetError(
+        "PreMan needs uv to add its tool decorators. Install it (https://docs.astral.sh/uv/) and re-run `preman eval target`."
+      );
+    }
+    const line = String(ran.stdout || "").trim().split("\n").pop() || "";
+    let out;
+    try {
+      out = JSON.parse(line);
+    } catch {
+      throw new TargetError(`PreMan could not plan its tool decorators: ${plannerFailure(ran)}`);
+    }
+    if (!out.ok) throw new TargetError(`PreMan could not plan its tool decorators: ${out.why}`);
+    return out;
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Why the planner printed no plan: how it ended, then the end of what it said. */
+function plannerFailure(ran) {
+  const cause =
+    ran.error?.code === "ETIMEDOUT"
+      ? `it did not finish within ${DECORATE_TIMEOUT_MS / 60_000} minutes`
+      : ran.signal
+        ? `it was stopped by ${ran.signal}`
+        : ran.error
+          ? ran.error.message
+          : ran.status
+            ? `it exited with status ${ran.status}`
+            : "it printed no plan";
+  const tail = (ran.stderr || "").trim().slice(-400);
+  return tail ? `${cause}: ${tail}` : cause;
+}
+
+/**
+ * Put @preman_tool on the agent's tools, with the customer's yes. Returns the
+ * answer with `tools` replaced by what the wrapper should watch, and the
+ * repository-relative files that now carry decorators.
+ *
+ * Nothing is installed: the block the edit writes falls back to a decorator
+ * that does nothing wherever PreMan's recorder is not importable, which is
+ * everywhere but an eval. Declining is allowed: the eval still runs and every
+ * turn says tool calls were not recorded.
+ */
+async function applyDecorations(found, { root, log }) {
+  if (!DECORATED_SHAPES.has(String(found.shape || "")) || !(found.tools || []).length) {
+    return { found, edited: [] };
+  }
+  const plan = planDecorations(found, root);
+  for (const d of plan.dropped) log(`  not decorated: ${d.file}:${d.symbol} (${d.why})`);
+  for (const c of plan.covered) log(`  recorded by the ${c.covered_by} tracing plugin, not decorated: ${c.file}:${c.symbol}`);
+  const watched = [...plan.decorate, ...plan.covered];
+  const edited = [...new Set(plan.decorate.map((d) => d.file))];
+  if (!plan.files.length) return { found: { ...found, tools: watched }, edited };
+
+  log("");
+  log("To record this agent's tool calls, PreMan would make these changes to your code:");
+  log("");
+  log(plan.diff);
+  log(
+    "@preman_tool records only while a PreMan eval is running. Everywhere else it leaves " +
+      "your function unchanged, and nothing needs installing."
+  );
+  const answer = await ask("Make these changes? [y]es / [n]o: ");
+  if (!answer.startsWith("y")) {
+    log("No changes made. The eval will run, but its tool calls will not be recorded.");
+    return {
+      found: {
+        ...found,
+        tools: plan.covered,
+        tools_not_recorded: "the @preman_tool decorators were not added, so tool calls are not recorded",
+      },
+      edited: [],
+    };
+  }
+  // A file saved while the question was open would lose that edit.
+  const changed = plan.files.filter((f) => {
+    try {
+      return readFileSync(path.join(root, f.path), "utf8") !== f.before;
+    } catch {
+      return true;
+    }
+  });
+  if (changed.length) {
+    throw new TargetError(
+      `${changed.map((f) => f.path).join(", ")} changed while PreMan was asking, so nothing was written. ` +
+        "Re-run `preman eval target` to see the changes against your current code."
+    );
+  }
+  for (const f of plan.files) writeFileSync(path.join(root, f.path), f.after, "utf8");
+  return { found: { ...found, tools: watched }, edited };
+}
+
+async function installShim(found, built, { projectPath, args, log, edited = [] }) {
   const { root, dir, file } = writeShim(projectPath, built.shim);
   const alsoWrote = [];
   if (built.bridge) {
@@ -762,7 +890,7 @@ async function installShim(found, built, { projectPath, args, log }) {
 
   const finalSource = readFileSync(file, "utf8");
   const language = String(found.language || "python").toLowerCase() === "node" ? "node" : "python";
-  const entry = record(found, file, root, finalSource, { language, alsoWrote });
+  const entry = record(found, file, root, finalSource, { language, alsoWrote, edited });
   log(`Approved. ${REPO_CONFIG} remembers it, so this will not be asked again.`);
 
   return verifyEntry({ ...entry, root });