pal-code 0.1.0__py3-none-any.whl

pal/studio/catalog.py

@@ -0,0 +1,90 @@
+"""What the bot can choose from: build roles, tools, and access permissions.
+
+The bot proposes; the person decides. Every item here has a plain description so the page can show what was chosen and why.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from pal import tool_catalog
+
+
+@dataclass(frozen=True)
+class Role:
+    id: str
+    name: str
+    description: str
+    prompt: str                # what this role is told it is, kept short: it is sent with every request
+
+
+ROLES: dict[str, Role] = {r.id: r for r in (
+    Role("designer", "Designer", "Plans the look and layout: pages, styling, user-interface structure.",
+         "You are the designer. You decide the layout and write the styles and markup. Keep it clean, readable and responsive."),
+    Role("coder", "Coder", "Writes the working code: the logic and the main files.",
+         "You are the coder. You write complete, working code. No placeholders, no TODOs, no explanations inside code."),
+    Role("tester", "Tester", "Writes tests and checks that the pieces fit together.",
+         "You are the tester. You write small, clear tests for what exists and point out what does not fit together."),
+    Role("docs", "Docs writer", "Writes the README and usage instructions.",
+         "You are the documentation writer. You write a short README: what it is, how to run it, one example."),
+    Role("reviewer", "Reviewer", "Reads everything that was written and fixes mistakes.",
+         "You are the reviewer. You read all the files so far, find mistakes and mismatches, and give corrected files."),
+)}
+ROLE_ORDER = tuple(ROLES)
+
+
+@dataclass(frozen=True)
+class Permission:
+    id: str
+    title: str
+    description: str
+    default: bool
+    risky: bool = False         # only the person can switch it on: the bot may suggest it but never enables it
+    locked: bool = False        # cannot be changed in this version
+    why_locked: str = ""
+
+
+PERMISSIONS: tuple[Permission, ...] = (
+    Permission("write_project", "Save files in the project folder", "The build writes the files it creates into its own project folder. Off: a dry run that shows the files but saves nothing.", True),
+    Permission("modify_own_files", "Change files it already wrote", "Later steps (the reviewer, fixes) may rewrite a file an earlier step created in this build.", True),
+    Permission("read_references", "Read the reference files you attach", "The bot may read documents you attach as reference (a brief, a design doc). They stay on this machine unless you use an API model.", True),
+    Permission("network_access", "Go online", "Tools that reach the internet (Wikipedia, arXiv, web fetch, search). Off by default: it sends queries off this machine.", False, risky=True),
+    Permission("run_code", "Run the code it writes", "Running generated code needs a proper sandbox, which this version does not have. The build checks files for syntax mistakes instead.", False, locked=True,
+               why_locked="needs a sandbox (not in this version)"),
+    Permission("outside_project", "Touch files outside the project folder", "Never. Every path must stay inside the project folder.", False, locked=True, why_locked="never allowed"),
+    Permission("delete_files", "Delete files", "Never. The build only creates and rewrites files.", False, locked=True, why_locked="never allowed"),
+)
+PERMISSION_BY_ID = {p.id: p for p in PERMISSIONS}
+DEFAULT_PERMISSIONS = {p.id: p.default for p in PERMISSIONS}
+
+# Tools the builder's own file handling replaces, or that need a loaded project: not offered as choices.
+_NOT_OFFERED = frozenset({"save_file", "read_file", "write_file", "list_files", "file_to_markdown", "build_code_graph", "query_code_graph", "read_source", "find_usages",
+                          "search_source", "list_project_files", "system_info", "word_count"})
+DOCUMENT_TOOLS = frozenset({"search_documents", "read_document", "document_outline"})
+NETWORK_TOOLS = frozenset({"wikipedia", "arxiv_search", "http_get", "google_search", "wolfram_alpha", "currency_convert", "moon_phase", "words_api",
+                           "image_caption", "visual_question_answering", "text_to_image", "text_to_audio", "speech_to_text"})
+OFFERED_TOOLS = tuple(e.name for e in tool_catalog.CATALOG if e.name not in _NOT_OFFERED)
+
+
+def tool_needs(name: str) -> str | None:
+    """The permission a tool needs: going online, or reading the files you attached."""
+    if name in NETWORK_TOOLS:
+        return "network_access"
+    if name in DOCUMENT_TOOLS:
+        return "read_references"
+    return None
+
+
+def catalog(tools_cfg, env: Mapping[str, str]) -> dict:
+    """Everything the page can offer, as plain data. `ready` is false for a tool that has to be switched on in the settings first."""
+    tools = []
+    for name in OFFERED_TOOLS:
+        e = tool_catalog.BY_NAME[name]
+        st = tool_catalog.state(e, tools_cfg, env)
+        tools.append({"name": name, "title": e.title, "group": e.group, "summary": e.summary, "needs": tool_needs(name), "state": st,
+                      "ready": st in ("", "ready"), "why_not": "" if st in ("", "ready") else (f"{st}: set it in the settings" if st != "off" else "off in the settings (tools.services / tools.network)")})
+    return {
+        "roles": [{"id": r.id, "name": r.name, "description": r.description} for r in ROLES.values()],
+        "tools": tools,
+        "permissions": [{"id": p.id, "title": p.title, "description": p.description, "default": p.default, "risky": p.risky, "locked": p.locked, "why_locked": p.why_locked} for p in PERMISSIONS],
+    }

pal/studio/checks.py

@@ -0,0 +1,129 @@
+"""Static checks on the files a build wrote. Nothing is run: a file is read, never executed.
+
+These catch the mistakes small models make most (a half-closed tag, a missing brace, a page that links to a file that was never written). A problem is
+reported in plain words so it can be sent back to the model once for a fix.
+"""
+from __future__ import annotations
+
+import ast
+import json
+import re
+from html.parser import HTMLParser
+from pathlib import PurePosixPath
+
+_VOID = frozenset({"area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"})
+_TRACKED = frozenset({"html", "head", "body", "script", "style", "div", "section", "nav", "main", "header", "footer", "form", "table", "ul", "ol", "button"})
+_PAIRS = {"{": "}", "(": ")", "[": "]"}
+
+
+class _Html(HTMLParser):
+    def __init__(self):
+        super().__init__(convert_charrefs=True)
+        self.stack: list[str] = []
+        self.problems: list[str] = []
+        self.refs: list[str] = []
+
+    def handle_starttag(self, tag, attrs):
+        a = dict(attrs)
+        for key in ("src", "href"):
+            v = a.get(key)
+            if v and tag in ("script", "link", "img", "source") and not re.match(r"^([a-z][a-z0-9+.-]*:|//|#|data:)", v, re.I):
+                self.refs.append(v.split("#")[0].split("?")[0])
+        if tag in _TRACKED:
+            self.stack.append(tag)
+
+    def handle_startendtag(self, tag, attrs):
+        self.handle_starttag(tag, attrs)
+        if tag in _TRACKED and self.stack and self.stack[-1] == tag:
+            self.stack.pop()
+
+    def handle_endtag(self, tag):
+        if tag in _VOID or tag not in _TRACKED:
+            return
+        if tag in self.stack:
+            while self.stack and self.stack[-1] != tag:
+                self.problems.append(f"<{self.stack.pop()}> is never closed")
+            self.stack.pop()
+        else:
+            self.problems.append(f"</{tag}> closes something that was never opened")
+
+
+def _balance(code: str, comments: bool = True) -> list[str]:
+    """Brackets that do not pair up, ignoring strings and comments (a lightweight scan, not a parser)."""
+    stack: list[str] = []
+    i, n = 0, len(code)
+    while i < n:
+        c = code[i]
+        if comments and code.startswith("//", i):
+            i = code.find("\n", i)
+            i = n if i < 0 else i
+            continue
+        if comments and code.startswith("/*", i):
+            j = code.find("*/", i + 2)
+            i = n if j < 0 else j + 2
+            continue
+        if c in "\"'`":
+            j = i + 1
+            while j < n and code[j] != c:
+                j += 2 if code[j] == "\\" else 1
+                if c != "`" and j < n and code[j] == "\n":
+                    break
+            i = j + 1
+            continue
+        if c in _PAIRS:
+            stack.append(c)
+        elif c in _PAIRS.values():
+            if not stack or _PAIRS[stack[-1]] != c:
+                return [f"a '{c}' has no matching opener"]
+            stack.pop()
+        i += 1
+    return [f"a '{stack[-1]}' is never closed"] if stack else []
+
+
+def check_file(path: str, content: str) -> list[str]:
+    ext = PurePosixPath(path).suffix.lower()
+    if ext == ".py":
+        try:
+            ast.parse(content)
+        except SyntaxError as e:
+            return [f"syntax error on line {e.lineno}: {e.msg}"]
+    elif ext == ".json":
+        try:
+            json.loads(content)
+        except ValueError as e:
+            return [f"not valid JSON: {e}"]
+    elif ext in (".html", ".htm"):
+        p = _Html()
+        p.feed(content)
+        p.close()
+        return p.problems[:3] + [f"<{t}> is never closed" for t in p.stack[:3]]
+    elif ext in (".js", ".mjs", ".ts", ".tsx", ".jsx", ".css"):
+        return _balance(content, comments=True)
+    return []
+
+
+def check_project(files: dict[str, str], only: set[str] | None = None, links: bool = True) -> dict[str, list[str]]:
+    """Problems by file. `only` limits the single-file checks to files that just changed. `links` also checks that every file a page links to was
+    written: leave it off in the middle of a build, because a page may link to a file a later step is about to write."""
+    out: dict[str, list[str]] = {}
+    lower = {p.lower() for p in files}
+    for path, content in files.items():
+        problems = check_file(path, content) if only is None or path in only else []
+        if links and PurePosixPath(path).suffix.lower() in (".html", ".htm"):
+            p = _Html()
+            p.feed(content)
+            base = PurePosixPath(path).parent
+            for ref in p.refs:
+                target = (base / ref).as_posix() if str(base) != "." else ref
+                parts: list[str] = []
+                for seg in target.split("/"):
+                    if seg == "..":
+                        if parts:
+                            parts.pop()
+                    elif seg not in ("", "."):
+                        parts.append(seg)
+                if "/".join(parts).lower() not in lower:
+                    problems.append(f"it refers to {ref}, but no file with that name was written")
+        if problems:
+            out[path] = problems
+    return out

pal/studio/clients.py

@@ -0,0 +1,6 @@
+"""Moved to pal.terminal.clients; this name is kept so the Studio and older imports keep working."""
+import sys
+
+from pal.terminal import clients as _moved
+
+sys.modules[__name__] = _moved

pal/studio/editor.py

@@ -0,0 +1,137 @@
+"""The code editor behind the Studio: open a built project, change a file by hand, or ask Pal to change it.
+
+Every "ask" goes through the same token-saving client the builds use (PalClient), kept alive for the whole editing session, so the history is paged
+and compressed and the project's other files are indexed once instead of pasted again. Nothing Pal writes is saved until the person accepts it:
+`ask` only proposes (old text, new text, a diff); `save_file` is the one place a file changes, and it applies the same path and size rules as a build.
+"""
+from __future__ import annotations
+
+import re
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from pal.errors import UserInputError
+from pal.studio.builder import FORMAT
+from pal.studio.policy import MAX_FILE_BYTES, MAX_FILES, MAX_TOTAL_BYTES, PolicyError, safe_path
+from pal.terminal.files import _FENCE, parse_files
+from pal.terminal.session import diff_lines  # noqa: F401  (one diff, shared with the terminal)
+from pal.tokens import estimate_tokens
+
+SYSTEM = "You are a careful senior developer editing an existing project. You change only what was asked, and keep every file consistent with the others."
+MAX_DIFF_LINES = 400
+MAX_INSTRUCTION = 4000
+
+
+def lookup(files: dict[str, str], path: str) -> str | None:
+    """The stored name of `path`, compared without regard to case (Windows and macOS treat Index.html and index.html as one file)."""
+    low = path.lower()
+    return next((p for p in files if p.lower() == low), None)
+
+
+def save_file(state, path: str, content: str) -> dict:
+    """Write one file into a finished build (memory, and the project folder when the build was saved). Raises UserInputError with a plain reason."""
+    if state.build is None:
+        raise UserInputError("this build has no files yet")
+    try:
+        clean = safe_path(path)
+    except PolicyError as e:
+        raise UserInputError(str(e)) from None
+    if not isinstance(content, str):
+        raise UserInputError("the file's text must be a string")
+    size = len(content.encode("utf-8"))
+    if size > MAX_FILE_BYTES:
+        raise UserInputError(f"too big ({size // 1000} KB; the limit is {MAX_FILE_BYTES // 1000} KB)")
+    files = state.build.files
+    name = lookup(files, clean) or clean
+    if name not in files and len(files) >= MAX_FILES:
+        raise UserInputError(f"too many files (the limit is {MAX_FILES})")
+    if sum(len(c.encode("utf-8")) for p, c in files.items() if p != name) + size > MAX_TOTAL_BYTES:
+        raise UserInputError(f"the project would be over {MAX_TOTAL_BYTES // 1_000_000} MB")
+    if state.workspace is not None:
+        target = (state.workspace / name).resolve()
+        if state.workspace.resolve() not in target.parents:
+            raise UserInputError("files must stay inside the project folder")
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8", newline="")
+    files[name] = content
+    return {"path": name, "bytes": size, "saved_to_disk": state.workspace is not None}
+
+
+@dataclass
+class EditorSession:
+    """One editing conversation about one build. Holds the token-saving client and the running totals."""
+    client: Any
+    product: str
+    lock: threading.Lock = field(default_factory=threading.Lock)
+    sent: dict[str, str] = field(default_factory=dict)       # path -> the text Pal's index last received
+    history_tokens: int = 0                                  # what a plain chat would carry along: every earlier request and reply
+    asks: int = 0
+    pal_tokens: int = 0
+    helper_tokens: int = 0
+    plain_tokens: int = 0
+
+    def ask(self, files: dict[str, str], path: str, instruction: str) -> dict:
+        if not self.lock.acquire(blocking=False):
+            raise UserInputError("Pal is still working on your last request: wait for it to finish")
+        try:
+            return self._ask(files, path, instruction)
+        finally:
+            self.lock.release()
+
+    def _ask(self, files: dict[str, str], path: str, instruction: str) -> dict:
+        name = lookup(files, path) if path else None
+        others = {p: c for p, c in files.items() if p != name}
+        changed = [{"name": p, "text": c, "kind": "document"} for p, c in others.items() if self.sent.get(p) != c]
+        listing = "\n".join(f"- {p} ({len(c.encode('utf-8')):,} bytes)" for p, c in sorted(files.items()))
+        parts = [f"Project: {self.product}. Files:\n{listing}", "The other files are available to you as reference documents; read them only if the change needs them."]
+        if name:
+            parts.append(f"The file open in the editor is {name}. Its current content:\n```\n{files[name]}\n```")
+        parts += [f"Change requested: {instruction}",
+                  "Reply with the COMPLETE new content of every file you change (never a fragment, never '...'), and leave other files out. " + FORMAT
+                  + " If the request is only a question, answer in a few sentences and write no files."]
+        message = "\n\n".join(parts)
+        # what a plain chat client would have sent for this same request: the system line, the whole project, every earlier turn, and the request
+        plain_prompt = estimate_tokens(SYSTEM) + sum(estimate_tokens(c) for c in files.values()) + estimate_tokens(listing) + self.history_tokens + estimate_tokens(instruction)
+        reply = self.client.ask(message, changed or None)
+        for p, c in others.items():
+            self.sent[p] = c
+        self.asks += 1
+        self.pal_tokens += reply.prompt_tokens + reply.completion_tokens
+        self.helper_tokens += reply.helper_tokens
+        self.plain_tokens += plain_prompt + reply.completion_tokens
+        self.history_tokens += estimate_tokens(instruction) + estimate_tokens(reply.text)
+
+        parsed, _unnamed = parse_files(reply.text, default_name=name or "")
+        proposals, refused = [], []
+        for pf in parsed:
+            try:
+                clean = safe_path(pf.path)
+            except PolicyError as e:
+                refused.append({"path": pf.path[:80], "reason": str(e)})
+                continue
+            if len(pf.content.encode("utf-8")) > MAX_FILE_BYTES:
+                refused.append({"path": clean, "reason": f"too big (the limit is {MAX_FILE_BYTES // 1000} KB)"})
+                continue
+            existing = lookup(files, clean)
+            old = files[existing] if existing else ""
+            if existing and old == pf.content:
+                continue
+            proposals.append({"path": existing or clean, "new": not existing, "old": old, "content": pf.content, "diff": diff_lines(old, pf.content)})
+        note = " ".join(m.group(1).strip() for m in re.finditer(r"^NOTE:\s*(.+)$", reply.text, re.M))
+        talk = re.sub(r"^#+\s*FILE:.*$|^NOTE:.*$", "", _FENCE.sub("", reply.text), flags=re.M | re.I).strip()
+        return {"files": proposals, "refused": refused, "note": note, "message": talk[:1500],
+                "usage": {"prompt_tokens": reply.prompt_tokens, "completion_tokens": reply.completion_tokens, "helper_tokens": reply.helper_tokens, "seconds": round(reply.seconds, 1),
+                          "plain_estimate": plain_prompt + reply.completion_tokens},
+                "session": {"asks": self.asks, "pal_tokens": self.pal_tokens, "helper_tokens": self.helper_tokens, "plain_estimate": self.plain_tokens,
+                            "saved_pct": round(100.0 * (self.plain_tokens - self.pal_tokens) / self.plain_tokens, 1) if self.plain_tokens else 0.0}}
+
+    def close(self) -> None:
+        close = getattr(self.client, "close", None)
+        if close:
+            close()
+
+
+def new_session_dir(root: Path, run_id: str, arm: str) -> Path:
+    return root / run_id / f"{arm}-edit-home"

pal/studio/files.py

@@ -0,0 +1,6 @@
+"""Moved to pal.terminal.files; this name is kept so the Studio and older imports keep working."""
+import sys
+
+from pal.terminal import files as _moved
+
+sys.modules[__name__] = _moved

pal/studio/models.py

@@ -0,0 +1,6 @@
+"""Moved to pal.terminal.models; this name is kept so the Studio and older imports keep working."""
+import sys
+
+from pal.terminal import models as _moved
+
+sys.modules[__name__] = _moved

pal/studio/plan.py

@@ -0,0 +1,149 @@
+"""The plan: what the bot proposes and what the person edits. One normaliser enforces every rule, whoever changed the plan.
+
+The rules that matter:
+  * a risky permission (going online) can be on only if the PERSON switched it on (`user_set`): the bot may suggest it, never enable it;
+  * a locked permission (running code, touching files outside the project, deleting) is always off;
+  * a tool that needs a permission is dropped when that permission is off, and the plan says so;
+  * unknown roles, tools and permissions are dropped, so a model's invention can never become an action.
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Mapping
+
+from pal.llm_wrapper.modes import PROVIDER_KEYS, mode_for
+from pal.studio.catalog import DEFAULT_PERMISSIONS, OFFERED_TOOLS, PERMISSION_BY_ID, ROLE_ORDER, ROLES, tool_needs
+
+KINDS = ("web_app", "cli_tool", "library", "script", "document", "other")
+MAX_STEPS, MAX_ROLES = 8, 5
+_FOLDER = re.compile(r"[^a-z0-9]+")
+
+
+_DEVICE = frozenset({"con", "prn", "aux", "nul", *(f"com{i}" for i in range(1, 10)), *(f"lpt{i}" for i in range(1, 10))})
+
+
+def slug(name: str) -> str:
+    """A safe folder name for a product. A name that is a Windows device name (con, nul, aux ...) would break there, so it gets a prefix."""
+    out = _FOLDER.sub("-", name.lower()).strip("-")[:40] or "project"
+    return f"p-{out}" if out in _DEVICE else out
+
+
+def _mapping(value) -> Mapping:
+    return value if isinstance(value, Mapping) else {}
+
+
+def _text(value, limit: int) -> str:
+    return " ".join(str(value or "").split())[:limit]
+
+
+def default_steps(roles: list[str], summary: str | None = "") -> list[dict]:
+    task = {"designer": "Design the layout and write the styles and markup.", "coder": "Write the working code and the main files.",
+            "tester": "Write tests for what exists.", "docs": "Write the README: what it is, how to run it, one example.",
+            "reviewer": "Review every file written so far and give corrected versions of any with mistakes."}
+    return [{"role": r, "task": task[r]} for r in ROLE_ORDER if r in roles]
+
+
+def normalize(raw: Mapping | None, *, installed: Iterable[str] = (), recommended: str | None = None, user_set: Iterable[str] = (),
+              ready_tools: Iterable[str] | None = None) -> tuple[dict, list[str]]:
+    """Any proposed plan -> (a valid plan, the notes about what had to change). `installed` are the local models that exist; `ready_tools` the
+    tools that can be used right now (None: every offered tool)."""
+    raw = dict(raw or {})
+    notes: list[str] = []
+    user_set = set(user_set)
+    installed = list(installed)
+    ready = set(OFFERED_TOOLS if ready_tools is None else ready_tools)
+
+    prod = _mapping(raw.get("product"))
+    kind = prod.get("kind") if prod.get("kind") in KINDS else "web_app"
+    name = _text(prod.get("name"), 60) or "My project"
+    product = {"name": name, "summary": _text(prod.get("summary"), 400), "kind": kind, "folder": slug(name)}
+
+    roles = []
+    for r in raw.get("roles") or []:
+        if isinstance(r, str) and r in ROLES and r not in roles:
+            roles.append(r)
+        elif isinstance(r, str) and r not in ROLES:
+            notes.append(f"dropped an agent that does not exist: {_text(r, 30)}")
+    roles = [r for r in ROLE_ORDER if r in roles][:MAX_ROLES]
+    if "coder" not in roles:
+        roles.insert(0, "coder")
+        notes.append("added the Coder: a build needs someone to write the code")
+        roles = [r for r in ROLE_ORDER if r in roles]
+
+    perms = dict(DEFAULT_PERMISSIONS)
+    given = _mapping(raw.get("permissions"))
+    for pid, want in given.items():
+        p = PERMISSION_BY_ID.get(pid)
+        if p is None:
+            notes.append(f"dropped a permission that does not exist: {_text(pid, 30)}")
+            continue
+        if p.locked:
+            if want:
+                notes.append(f"{p.title} stays off: {p.why_locked}")
+            continue
+        if want and p.risky and pid not in user_set:
+            notes.append(f"{p.title} stays off: only you can switch it on (use the switch in Access)")
+            continue
+        perms[pid] = bool(want)
+
+    tools = []
+    for t in raw.get("tools") or []:
+        if not isinstance(t, str) or t in tools:
+            continue
+        if t not in OFFERED_TOOLS:
+            notes.append(f"dropped a tool that is not available to builds: {_text(t, 30)}")
+            continue
+        need = tool_needs(t)
+        if need and not perms.get(need):
+            notes.append(f"left out {t}: it needs '{PERMISSION_BY_ID[need].title}', which is off")
+            continue
+        if t not in ready:
+            notes.append(f"left out {t}: it is not switched on in the settings")
+            continue
+        tools.append(t)
+
+    m = _mapping(raw.get("model"))
+    if m.get("mode") == "api" and m.get("provider") in PROVIDER_KEYS and _text(m.get("model"), 120):
+        model = {"mode": "api", "provider": m["provider"], "model": _text(m["model"], 120), "api_mode": mode_for(m["provider"])}
+    else:
+        pick = m.get("model") if m.get("mode") == "local" and m.get("model") in installed else (recommended or (installed[0] if installed else ""))
+        model = {"mode": "local", "model": pick or "", "provider": "ollama", "api_mode": ""}
+        if m.get("mode") == "local" and m.get("model") and m.get("model") not in installed and installed:
+            notes.append(f"{_text(m['model'], 40)} is not installed: using {pick}")
+
+    steps = []
+    for s in raw.get("steps") or []:
+        if isinstance(s, Mapping) and s.get("role") in roles and _text(s.get("task"), 300):
+            steps.append({"role": s["role"], "task": _text(s["task"], 300)})
+    steps = steps[:MAX_STEPS] or default_steps(roles, product["summary"])
+
+    reasons = {}
+    for key, why in _mapping(raw.get("reasons")).items():
+        kind_, _, ident = str(key).partition(":")
+        if (kind_ == "role" and ident in roles) or (kind_ == "tool" and ident in tools) or (kind_ == "permission" and ident in PERMISSION_BY_ID) or key in ("model", "metrics"):
+            reasons[str(key)] = _text(why, 200)
+
+    return {"product": product, "roles": roles, "tools": tools, "permissions": perms, "model": model, "steps": steps, "reasons": reasons,
+            "metrics": bool(raw.get("metrics"))}, notes
+
+
+def diff(old: Mapping, new: Mapping) -> list[str]:
+    """What changed between two plans, in words the person can read."""
+    out: list[str] = []
+    for key, label in (("roles", "agent"), ("tools", "tool")):
+        a, b = set(old.get(key, [])), set(new.get(key, []))
+        out += [f"added {label}: {ROLES[x].name if key == 'roles' and x in ROLES else x}" for x in new.get(key, []) if x not in a]
+        out += [f"removed {label}: {ROLES[x].name if key == 'roles' and x in ROLES else x}" for x in old.get(key, []) if x not in b]
+    for pid, now in new.get("permissions", {}).items():
+        if old.get("permissions", {}).get(pid) != now:
+            out.append(f"{'turned on' if now else 'turned off'}: {PERMISSION_BY_ID[pid].title.lower()}")
+    if old.get("model") != new.get("model"):
+        nm = new["model"]
+        out.append(f"model: {nm['model'] or 'none'} ({'API, ' + nm['provider'] if nm['mode'] == 'api' else 'local'})")
+    if old.get("steps") != new.get("steps"):
+        out.append(f"steps changed ({len(new.get('steps', []))} now)")
+    if old.get("product") != new.get("product"):
+        out.append("product description changed")
+    if bool(old.get("metrics")) != bool(new.get("metrics")):
+        out.append("build twice to compare: " + ("on" if new.get("metrics") else "off"))
+    return out