rlmness-cli 0.2.0__py3-none-any.whl

rlmagent/planning.py

@@ -0,0 +1,84 @@
+"""Plan mode: a read-only stance for the agent."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import replace
+
+from rlmagent.safety import is_safe_command
+from rlmagent.harness.contracts.tooling import (
+    CancelToken,
+    ProgressNotifier,
+    ToolOutcome,
+    ToolSpec,
+)
+from rlmagent.harness.contracts.values import JValue
+
+#: Tools removed entirely while plan mode is active.
+#: The python kernel can write anything, so it cannot be limited to reading.
+MUTATING_TOOLS = frozenset({"Write", "Edit", "ApplyPatch", "python"})
+
+#: Tool whose commands are filtered rather than removed.
+_SHELL_TOOL = "Bash"
+
+_REFUSAL = (
+    "Plan mode is active: {tool} may only run read-only commands. "
+    "Refused: {command!r}. Present your plan and ask the user to leave "
+    "plan mode before running this."
+)
+
+PLAN_MODE_INSTRUCTIONS = """## Plan mode
+
+Plan mode is active. Research the codebase and produce a plan — do not \
+change anything.
+
+- Read files, inspect the tree, and run read-only shell commands freely.
+- Do not create, modify, or delete files, and do not run commands with side \
+effects. The tools to do so are unavailable or will refuse.
+- Finish by presenting a concrete, ordered implementation plan: the files to \
+touch, the change in each, and how the result gets verified.
+- Ask the user to leave plan mode (`/plan off`) before implementing anything."""
+
+
+def _guard_shell(tool: ToolSpec) -> ToolSpec:
+    """Wrap a shell tool so only read-only commands reach the real handler."""
+    inner = tool.run
+
+    async def run(
+        tool_call_id: str,
+        arguments: Mapping[str, JValue],
+        signal: CancelToken | None = None,
+        on_update: ProgressNotifier | None = None,
+    ) -> ToolOutcome:
+        command = arguments.get("command")
+        if not isinstance(command, str) or not is_safe_command(command):
+            return ToolOutcome(
+                content=_REFUSAL.format(tool=tool.name, command=command),
+                details={"error": "plan_mode"},
+            )
+        return await inner(tool_call_id, arguments, signal, on_update)
+
+    return replace(tool, run=run)
+
+
+def restrict_tools(tools: Sequence[ToolSpec]) -> list[ToolSpec]:
+    """Return *tools* with mutating entries dropped and the shell guarded."""
+    restricted: list[ToolSpec] = []
+    for tool in tools:
+        if tool.name in MUTATING_TOOLS:
+            continue
+        restricted.append(_guard_shell(tool) if tool.name == _SHELL_TOOL else tool)
+    return restricted
+
+
+def plan_system_prompt(system: str) -> str:
+    """Append the plan-mode instruction block to a base system prompt."""
+    return f"{system}\n\n{PLAN_MODE_INSTRUCTIONS}"
+
+
+__all__ = [
+    "MUTATING_TOOLS",
+    "PLAN_MODE_INSTRUCTIONS",
+    "plan_system_prompt",
+    "restrict_tools",
+]

rlmagent/playbook/__init__.py

@@ -0,0 +1 @@
+"""The agent's playbook: rules, memories, skills and roles it keeps between runs."""

rlmagent/playbook/apply.py

@@ -0,0 +1,106 @@
+"""Check proposed playbook edits and apply the valid ones; build the edits that undo a change."""
+
+from __future__ import annotations
+
+import ast
+import time
+import uuid
+from dataclasses import asdict
+
+from rlmagent.playbook.store import KINDS, Entry, Playbook
+
+ACTIONS = ("create", "update", "delete")
+
+
+def validate(edit: dict) -> str | None:
+    action, kind = edit.get("action"), edit.get("kind")
+    if action not in ACTIONS:
+        return f"action must be one of {ACTIONS}"
+    if not str(edit.get("id") or "").strip():
+        return "id is required"
+    if action == "delete":
+        return None
+    if kind not in KINDS:
+        return f"kind must be one of {KINDS}"
+    life = edit.get("expires_after_tasks")
+    if life is not None and (not isinstance(life, int) or isinstance(life, bool) or life < 1):
+        return "expires_after_tasks must be a positive whole number"
+    if not str(edit.get("title") or "").strip() or not str(edit.get("content") or "").strip():
+        return "title and content are required"
+    if kind == "skill":
+        name = edit.get("callable")
+        if not name:
+            return "a skill needs `callable`: the function its code defines"
+        try:
+            tree = ast.parse(edit["content"])
+        except SyntaxError as exc:
+            return f"skill content is not valid Python: {exc.msg}"
+        defined = {n.name for n in tree.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))}
+        if name not in defined:
+            return f"skill content never defines {name}()"
+    return None
+
+
+def apply_edits(pb: Playbook, edits: list[dict], *, baseline: dict[str, int], scope: str,
+                trigger: str, summary: str, rationale: str = "",
+                read_only: Playbook | None = None) -> dict:
+    """Apply what is valid; record every edit, applied or not, in `pb.history`."""
+    changes = []
+    for edit in edits:
+        eid = str(edit.get("id") or "").removeprefix("local:")
+        before = pb.entries.get(eid)
+        error = validate(edit)
+        if error is None:
+            error = _conflict(edit, eid, before, baseline, read_only)
+        change = {"action": edit.get("action"), "id": eid, "kind": edit.get("kind"),
+                  "applied": error is None, "error": error,
+                  "before": asdict(before) if before else None, "after": None}
+        if error is None:
+            if edit["action"] == "delete":
+                del pb.entries[eid]
+            else:
+                entry = Entry(
+                    id=eid, kind=edit["kind"], title=edit["title"], content=edit["content"],
+                    scope=scope, callable=edit.get("callable"),
+                    version=(before.version + 1) if before else 1, updated=time.time(),
+                    expires_after_tasks=edit.get("expires_after_tasks"), made_at_task=pb.tasks,
+                )
+                pb.entries[eid] = entry
+                change["after"] = asdict(entry)
+        changes.append(change)
+    event = {"id": uuid.uuid4().hex[:8], "trigger": trigger, "scope": scope, "summary": summary,
+             "rationale": rationale, "time": time.time(), "changes": changes}
+    pb.history.append(event)
+    return event
+
+
+def _conflict(edit, eid, before, baseline, read_only) -> str | None:
+    action = edit["action"]
+    if read_only is not None and eid in read_only.entries and eid not in baseline and before is None:
+        return "shared entries are read-only here; create a local entry instead"
+    if action == "create" and before is not None:
+        return "an entry with this id already exists"
+    if action != "create" and before is None:
+        return "no entry with this id"
+    if before is not None and eid in baseline and baseline[eid] != before.version:
+        return "entry changed while this edit was being planned"
+    return None
+
+
+def reverse_edits(event: dict) -> list[dict]:
+    """Edits that undo the applied changes of `event`, newest first."""
+    out = []
+    for change in reversed(event["changes"]):
+        if not change["applied"]:
+            continue
+        if change["action"] == "create":
+            out.append({"action": "delete", "id": change["id"]})
+        elif change["action"] == "update":
+            out.append({"action": "update", **_as_edit(change["before"])})
+        else:
+            out.append({"action": "create", **_as_edit(change["before"])})
+    return out
+
+
+def _as_edit(entry: dict) -> dict:
+    return {k: entry[k] for k in ("id", "kind", "title", "content", "callable")}

rlmagent/playbook/digest.py

@@ -0,0 +1,63 @@
+"""The short view of the playbook the agent sees in its conversation."""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+
+from rlmagent.playbook.store import KINDS, Entry
+
+PER_KIND = 5
+WIDTH = 200
+
+_HEADER = """[Playbook] Entries you (or earlier sessions) kept for later. Follow the rules, \
+use the memories. In the python tool: `await playbook("id")` shows an entry in full, \
+`fn = await skill("id")` loads a skill as a function, and `await improve("what to \
+keep")` asks for the playbook to be updated from this conversation once the turn ends."""
+
+
+def _terms(text: str) -> set[str]:
+    return set(re.findall(r"[a-z0-9_]{3,}", text.lower()))
+
+
+def _weights(goal: str, recent: list[str]) -> dict[str, float]:
+    """Goal words weigh 3; recent messages weigh from 2 (newest) down to 1 (oldest)."""
+    weights: dict[str, float] = {}
+    for i, text in enumerate(recent):
+        w = 1 + (i / max(len(recent) - 1, 1))
+        for term in _terms(text):
+            weights[term] = max(weights.get(term, 0), w)
+    for term in _terms(goal):
+        weights[term] = 3.0
+    return weights
+
+
+def _score(entry_terms: set[str], weights: dict[str, float], rarity: dict[str, float]) -> float:
+    return sum(weights[t] * rarity.get(t, 1.0) for t in entry_terms if t in weights)
+
+
+def render(entries: list[Entry], goal: str = "", recent: list[str] | None = None,
+           per_kind: int = PER_KIND) -> str:
+    weights = _weights(goal, recent or [])
+    terms = {e.id: _terms(f"{e.id} {e.title} {e.content}") for e in entries}
+    counts: dict[str, int] = {}
+    for ts in terms.values():
+        for t in ts:
+            counts[t] = counts.get(t, 0) + 1
+    rarity = {t: math.log(1 + len(entries) / c) for t, c in counts.items()}
+    lines = [_HEADER]
+    for kind in KINDS:
+        chosen = [e for e in entries if e.kind == kind]
+        chosen.sort(key=lambda e: (-_score(terms[e.id], weights, rarity), -e.updated))
+        for e in chosen[:per_kind]:
+            text = " ".join(f"{e.title}: {e.content}".split())
+            if len(text) > WIDTH:
+                text = text[: WIDTH - 1] + "…"
+            lines.append(f"- [{kind}] {e.id}: {text}")
+    return "\n".join(lines)
+
+
+def fingerprint(entries: list[Entry]) -> str:
+    key = "|".join(sorted(f"{e.id}:{e.version}" for e in entries))
+    return hashlib.sha1(key.encode()).hexdigest()[:12]

rlmagent/playbook/improver.py

@@ -0,0 +1,272 @@
+"""Runs playbook updates for one session: when asked, between turns, with undo."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from pathlib import Path
+
+import json
+import time
+
+from rlmagent.playbook.apply import apply_edits, reverse_edits
+from rlmagent.playbook.digest import fingerprint, render
+
+from rlmagent.playbook.plan import (
+    AUTO_NOTE,
+    CHECK_CHARS,
+    CHECK_SYSTEM,
+    SYSTEM,
+    build_request,
+    parse_check,
+    parse_proposal,
+)
+from rlmagent.playbook.store import Playbook, load, merged, save
+
+#: How long a memory saved without being asked for lasts, in finished tasks. It
+#: was written from one moment of the work, which is what makes it go stale.
+AUTO_MEMORY_TASKS = 3
+#: Failed tool calls in one task that are worth a look for something to keep.
+TROUBLE_CALLS = 3
+
+
+class Improver:
+    def __init__(self, session, local_path: Path | None, shared_path: Path | None) -> None:
+        self.writable = True
+        self.session = session
+        self.paths = {"local": local_path, "global": shared_path}
+        self.local = load(local_path)
+        self.shared = load(shared_path)
+        self._pending: list[tuple[str | None, bool, str]] = []
+        self._shown: str | None = None
+        self.auto = True
+        self.every = 5
+        self.cooldown = 900.0
+        self._counted = 0
+        self._finished = 0
+        self._last_check = float("-inf")
+        self._compacted = False
+        # When set, proposals from automatic checks wait in held for /improve accept.
+        self.hold_auto = False
+        self.held: list[dict] = []
+
+    def _store(self, scope: str) -> Playbook:
+        if self.paths[scope] is not None:
+            fresh = load(self.paths[scope])
+            setattr(self, "local" if scope == "local" else "shared", fresh)
+        return self.local if scope == "local" else self.shared
+
+    def entries(self) -> list:
+        return merged(self.local, self.shared)
+
+    def entry(self, entry_id: str) -> dict:
+        for e in self.entries():
+            if e.id == entry_id:
+                return asdict(e)
+        raise KeyError(f"no playbook entry {entry_id!r}")
+
+    def request(self, instructions: str | None, shared: bool = False, trigger: str = "agent") -> None:
+        if not self.writable:
+            raise RuntimeError("playbook is read-only")
+        self._pending.append((instructions, shared, trigger))
+
+    async def run_pending(self) -> list[str]:
+        notes = []
+        while self._pending:
+            instructions, shared, trigger = self._pending.pop(0)
+            notes.append(await self.improve(instructions, shared=shared, trigger=trigger))
+        return notes
+
+    async def after_turn(self) -> None:
+        """Every `every` finished tasks (at most once per `cooldown` seconds), check.
+
+        Tasks rather than model turns: one task can take dozens of turns, and a
+        count of those lands in the middle of work that has nothing to teach yet.
+        A task that went badly is checked sooner, since that is where the lessons are.
+        """
+        if not self.auto or time.monotonic() - self._last_check < self.cooldown:
+            return
+        evidence = getattr(self.session, "evidence", None)
+        if evidence is not None and evidence.last_failed >= TROUBLE_CALLS:
+            self._counted = self._finished
+            await self._auto("auto:trouble")
+        elif self._finished - self._counted >= self.every:
+            self._counted = self._finished
+            await self._auto("auto:tasks")
+
+    def compacted(self) -> None:
+        """Note a compaction; the check runs at the next turn boundary, never inside a turn."""
+        self._compacted = True
+
+    def drop_pending(self) -> None:
+        self._pending.clear()
+        self._compacted = False
+
+    async def at_boundary(self) -> None:
+        self._finished += 1
+        await self._task_finished()
+        await self.run_pending()
+        if self._compacted:
+            self._compacted = False
+            if self.auto:
+                await self._auto("auto:compaction")
+        await self.after_turn()
+
+    async def _task_finished(self) -> None:
+        """Count the task in the session's playbook, and drop what has now gone stale."""
+        if not self.writable:
+            return
+        target = self._store("local")
+        target.tasks += 1
+        save(self.paths["local"], target)
+        stale = [e.id for e in target.entries.values()
+                 if e.expires_after_tasks is not None
+                 and target.tasks - e.made_at_task >= e.expires_after_tasks]
+        if stale:
+            event = self.apply([{"action": "delete", "id": eid} for eid in stale],
+                               trigger="expire", summary="written for work that has moved on")
+            await self._record(event)
+
+    async def _auto(self, trigger: str) -> None:
+        self._last_check = time.monotonic()
+        kept = "\n".join(f"- {e.id}: {e.title}: {e.content}" for e in self.entries()) or "(empty)"
+        prompt = f"Current playbook:\n{kept}\n\nRecent conversation:\n{self._conversation()[-CHECK_CHARS:]}"
+        worth_it, focus = parse_check(await self.session._utility_completion(prompt, CHECK_SYSTEM))
+        if worth_it:
+            instructions = f"{AUTO_NOTE}\nFocus: {focus}" if focus else AUTO_NOTE
+            await self.improve(instructions, trigger=trigger)
+
+    async def improve(self, instructions: str | None, *, shared: bool = False,
+                      trigger: str = "user") -> str:
+        if not self.writable:
+            return "Playbook is read-only."
+        scope = "global" if shared else "local"
+        target = self._store(scope)
+        baseline = {k: e.version for k, e in target.entries.items()}
+        request = build_request(self.entries(), target.history, self._conversation(),
+                                scope=scope, instructions=instructions)
+        try:
+            proposal = parse_proposal(await self.session._utility_completion(request, SYSTEM))
+        except ValueError as exc:
+            return f"Playbook not changed: {exc}"
+        if trigger.startswith("auto:"):
+            for edit in proposal["edits"]:
+                if isinstance(edit, dict) and edit.get("kind") == "memory":
+                    edit.setdefault("expires_after_tasks", AUTO_MEMORY_TASKS)
+            if self.hold_auto and proposal["edits"]:
+                self.held.append({"edits": proposal["edits"], "trigger": trigger, "scope": scope,
+                                  "summary": str(proposal.get("summary", "")),
+                                  "rationale": str(proposal.get("rationale", ""))})
+                return (f"Held proposal {len(self.held)} for review: "
+                        f"{proposal.get('summary', '')} (/improve pending)")
+        event = self.apply(proposal["edits"], trigger=trigger, scope=scope, baseline=baseline,
+                           summary=str(proposal.get("summary", "")),
+                           rationale=str(proposal.get("rationale", "")))
+        await self._record(event)
+        return _describe(event)
+
+    async def _record(self, event: dict) -> None:
+        """Log the change in the session, and in the shared log when it is shared."""
+        brief = {k: event[k] for k in ("id", "trigger", "scope", "summary", "time")}
+        brief["changes"] = [{k: c[k] for k in ("action", "id", "applied")} for c in event["changes"]]
+        note = getattr(self.session, "note_playbook_change", None)
+        if note is not None:
+            await note(brief)
+        shared = self.paths["global"]
+        if event["scope"] == "global" and shared is not None:
+            log = shared.with_name("playbook-changes.jsonl")
+            with log.open("a", encoding="utf-8") as f:
+                f.write(json.dumps(event, default=str) + "\n")
+
+    def apply(self, edits: list[dict], *, trigger: str, scope: str = "local",
+              baseline: dict | None = None, summary: str = "", rationale: str = "") -> dict:
+        if not self.writable:
+            raise RuntimeError("playbook is read-only")
+        target = self._store(scope)
+        if baseline is None:
+            baseline = {k: e.version for k, e in target.entries.items()}
+        event = apply_edits(target, edits, baseline=baseline, scope=scope, trigger=trigger,
+                            summary=summary, rationale=rationale,
+                            read_only=self.shared if scope == "local" else None)
+        save(self.paths[scope], target)
+        done = sorted({c["id"] for c in event["changes"] if c["applied"]})
+        evidence = getattr(self.session, "evidence", None)
+        if done and evidence is not None:
+            evidence.saved(event["id"], f"playbook:{trigger}", done, summary)
+        return event
+
+    async def undo(self, event_id: str) -> str:
+        for scope in ("local", "global"):
+            target = self._store(scope)
+            for event in target.history:
+                if event["id"] == event_id:
+                    undone = self.apply(reverse_edits(event), trigger="undo", scope=scope,
+                                        summary=f"undo {event_id}")
+                    await self._record(undone)
+                    return f"Change {event_id} undone. " + _describe(undone)
+        return f"No playbook change with id {event_id}."
+
+    def show_digest(self) -> None:
+        """Put the playbook in front of the model when it has changed since last shown."""
+        entries = self.entries()
+        fp = fingerprint(entries)
+        if fp == self._shown or (not entries and self._shown is None):
+            return
+        self._shown = fp
+        if not entries:
+            self.session.inject("[Playbook] Earlier entries no longer apply; it is now empty.")
+            return
+        transcript = self.session.transcript
+        goal = next((getattr(m, "text", "") for m in transcript if getattr(m, "role", "") == "user"), "")
+        recent = [getattr(m, "text", "") for m in transcript[-4:]]
+        self.session.inject(render(entries, goal=goal, recent=recent))
+
+    def _conversation(self) -> str:
+        return "\n".join(
+            f"[{getattr(m, 'role', '?')}] {getattr(m, 'text', '')}" for m in self.session.transcript
+        )
+
+    def pending_text(self) -> str:
+        if not self.held:
+            return "No proposals are waiting."
+        rows = []
+        for n, held in enumerate(self.held, 1):
+            rows.append(f"{n}. [{held['trigger']}] {held['summary']}")
+            rows += [f"   {e.get('action')} {e.get('kind', '')} {e.get('id', '')}: "
+                     f"{str(e.get('content', e.get('title', '')))[:200]}" for e in held["edits"]]
+        return "\n".join(rows)
+
+    async def _decide(self, words: list[str]) -> str:
+        if len(words) != 2 or not words[1].isdigit() or not 1 <= int(words[1]) <= len(self.held):
+            return f"Use /improve {words[0]} N, with N from /improve pending."
+        held = self.held.pop(int(words[1]) - 1)
+        if words[0] == "reject":
+            return f"Dropped: {held['summary']}"
+        event = self.apply(held["edits"], trigger=held["trigger"], scope=held["scope"],
+                           summary=held["summary"], rationale=held["rationale"])
+        await self._record(event)
+        self.show_digest()
+        return _describe(event)
+
+    async def command(self, arg: str) -> str:
+        words = arg.split()
+        if words[:1] == ["pending"]:
+            return self.pending_text()
+        if words[:1] in (["accept"], ["reject"]):
+            return await self._decide(words)
+        if words[:1] == ["list"]:
+            return "\n".join(f"{e.id} [{e.kind}, {e.scope}] {e.title}" for e in self.entries()) \
+                or "The playbook is empty."
+        if words[:1] == ["undo"] and len(words) == 2:
+            return await self.undo(words[1])
+        shared = "--shared" in words
+        instructions = " ".join(w for w in words if w != "--shared") or None
+        note = await self.improve(instructions, shared=shared, trigger="user")
+        self.show_digest()
+        return note
+
+
+def _describe(event: dict) -> str:
+    done = [f"{c['action']} {c['id']}" for c in event["changes"] if c["applied"]]
+    skipped = [f"{c['id']} ({c['error']})" for c in event["changes"] if not c["applied"]]
+    text = f"[{event['id']}] " + (", ".join(done) if done else "no change")
+    return text + (f"; skipped: {', '.join(skipped)}" if skipped else "")

rlmagent/playbook/plan.py

@@ -0,0 +1,99 @@
+"""Ask the model what to change in the playbook, and read its answer."""
+
+from __future__ import annotations
+
+import json
+import re
+
+from rlmagent.playbook.store import Entry
+
+CONVERSATION_CHARS = 60_000
+
+SYSTEM = """You maintain an agent's playbook: short entries the agent reads in later \
+turns and later sessions. Read the conversation and decide whether anything in it \
+is worth keeping. Most of the time the right answer is no change.
+
+Entry kinds:
+- rule: a narrow instruction for how to work ("run the tests before saying done").
+- memory: a fact, decision, preference or outcome worth remembering.
+- skill: a Python function the agent can reuse; `content` is its full source and \
+`callable` the name of the function it defines.
+- role: instructions for a kind of sub-agent the agent keeps starting.
+
+Only keep what the conversation shows: a repeated mistake, a correction from the \
+user, a procedure done more than once, a lasting fact. Prefer one small edit to \
+many; prefer updating an entry to adding a near-duplicate; delete entries shown to \
+be wrong. Never propose changes to source files.
+
+Answer with one JSON object and nothing else:
+{"summary": "one sentence", "rationale": "the evidence", "expected": "what should improve",
+ "edits": [{"action": "create|update|delete", "kind": "rule|memory|skill|role", "id": "short-id",
+            "title": "...", "content": "...", "callable": "only for skills",
+            "expires_after_tasks": "only for what stops being true once the current work moves \
+on: how many finished tasks to keep it"}]}
+An empty "edits" list is a good answer when nothing is worth keeping."""
+
+SCOPES = {
+    "local": "These edits apply to this session only. Shared entries are shown for context "
+             "and are read-only: to change one for this session, create a local entry.",
+    "global": "These edits are shared by every future session. Only keep what will still be "
+              "true later: user preferences, reusable skills and roles, facts about tools "
+              "or about a named project.",
+}
+
+
+CHECK_CHARS = 30_000
+
+CHECK_SYSTEM = """You decide whether an agent's recent conversation holds anything worth \
+keeping in its playbook: a correction from the user, a mistake made more than once, a \
+procedure done twice, a lasting fact or preference. Routine work, one-off details and \
+guesses are not worth keeping, and neither is anything the current playbook (shown \
+first) already holds. Answer with one JSON object and nothing else:
+{"worth_it": true or false, "why": "one sentence", "focus": "what to keep, if anything"}"""
+
+AUTO_NOTE = (
+    "This update was started automatically. No change is a good answer. Keep only what "
+    "the conversation clearly shows. Nothing goes to the shared playbook unless the user "
+    "asked for it."
+)
+
+
+def parse_check(text: str) -> tuple[bool, str]:
+    match = re.search(r"\{.*\}", text or "", re.S)
+    try:
+        answer = json.loads(match.group(0)) if match else {}
+    except json.JSONDecodeError:
+        answer = {}
+    return bool(answer.get("worth_it")), str(answer.get("focus") or "")
+
+
+def build_request(entries: list[Entry], history: list[dict], conversation: str, *,
+                  scope: str, instructions: str | None) -> str:
+    if len(conversation) > CONVERSATION_CHARS:
+        conversation = "[earlier conversation omitted]\n" + conversation[-CONVERSATION_CHARS:]
+    state = "\n".join(
+        f"- [{e.kind}] {e.id} (v{e.version}, {e.scope}): {e.title}\n  {e.content}" for e in entries
+    ) or "(empty)"
+    past = "\n".join(f"- {h['id']}: {h.get('summary', '')}" for h in history[-10:]) or "(none)"
+    parts = [
+        f"<playbook>\n{state}\n</playbook>",
+        f"<earlier_changes>\n{past}\n</earlier_changes>",
+        f"<scope>\n{SCOPES[scope]}\n</scope>",
+        f"<conversation>\n{conversation}\n</conversation>",
+    ]
+    if instructions:
+        parts.append(f"<instructions>\n{instructions}\n</instructions>")
+    return "\n\n".join(parts)
+
+
+def parse_proposal(text: str) -> dict:
+    match = re.search(r"\{.*\}", text or "", re.S)
+    if not match:
+        raise ValueError("the planner's answer contained no JSON object")
+    try:
+        proposal = json.loads(match.group(0))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"the planner's answer is not valid JSON: {exc}") from None
+    if not isinstance(proposal.get("edits"), list):
+        raise ValueError("the planner's JSON has no `edits` list")
+    return proposal