localcode 0.4.0__py3-none-macosx_13_0_arm64.whl

localcode/agent/plateau.py

@@ -0,0 +1,297 @@
+"""Plateau detector — stop a model that has reached its ceiling.
+
+Measured on HarnessBench 2026-09-08 (17 tasks, 27B model, 20 min cap): every
+task that hit the cap had already reached the oracle score other frontends got
+by STOPPING early. The model kept re-editing the same file and re-running the
+same experiments instead of writing the remaining deliverables. None of the
+existing breakers fire on that shape: each edit has different content, each
+command a different output, and the calls all succeed.
+
+"Progress" in a round is any of:
+  * a write/edit to a path not previously changed this turn (a NEW file or a
+    first touch of an existing one);
+  * a build/typecheck/test run that PASSED after the previous one this turn
+    failed, or the first pass this turn;
+  * a build/test run whose FAILURE SET moved on from the previous check this
+    turn: fewer failure lines, or the same count but a signature never seen
+    before this turn (a genuine debugging loop — the failure changes as the
+    model fixes things). A failure signature already seen this turn is NOT
+    progress: that is the true loop;
+  * a todo item transitioning to completed (or the list closing out).
+
+Everything else — reads, greps, re-edits of already-edited files, identical
+failing or repeat-passing test runs, throwaway experiments — is not progress.
+
+Policy: after `nudge_after` consecutive no-progress rounds, ONE wrap-up nudge
+naming the open plan items (finish the deliverables with what you have). After
+`stop_after` more, the turn ends with an honest summary — unless the most
+recent check this turn PASSED within the last `PLATEAU_PASS_WINDOW` rounds, in
+which case the model is told ONCE to finish now and given
+`PLATEAU_FINISH_ROUNDS` more rounds. Nothing fires in the first
+`PLATEAU_GRACE_ROUNDS` rounds so a slow start is never mistaken for a plateau.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+__all__ = [
+    "PlateauTracker",
+    "PLATEAU_GRACE_ROUNDS",
+    "PLATEAU_NUDGE_AFTER",
+    "PLATEAU_STOP_AFTER",
+    "PLATEAU_PASS_WINDOW",
+    "PLATEAU_FINISH_ROUNDS",
+    "failure_signature",
+]
+
+# Rounds (0-indexed) during which the detector never fires.
+PLATEAU_GRACE_ROUNDS = 4
+# Consecutive no-progress rounds before the wrap-up nudge.
+PLATEAU_NUDGE_AFTER = 6
+# Consecutive no-progress rounds AFTER the nudge before the turn ends.
+PLATEAU_STOP_AFTER = 8
+# A check that passed within this many rounds keeps the turn alive …
+PLATEAU_PASS_WINDOW = 2
+# … and the "finish now" nudge grants this many more rounds.
+PLATEAU_FINISH_ROUNDS = 3
+
+
+# ── failure-signature extraction ─────────────────────────────────────────
+_ANSI_RE = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]")
+# A path with at least one directory component: keep only the basename.
+_PATH_DIR_RE = re.compile(r"(?<![\w.])(?:[\w.~-]*/)+(?=[\w.-]+)")
+_NUM_RE = re.compile(r"\d+(?:\.\d+)?")
+_WS_RE = re.compile(r"\s+")
+_FAILURE_LINE_RE = re.compile(
+    r"FAILED|AssertionError|error TS|\berror\b|Error\b|✕|●|\bFAIL\b|Traceback|panic:",
+)
+_NOISE_LINE_RE = re.compile(
+    # summaries that mention errors without BEING a failure line (numbers
+    # are already normalised to N when this runs)
+    r"^\s*(?:=+.*=+|-+.*-+|(?:N|\d+) (?:passed|failed|error)s?\b.*|found (?:N|\d+) errors?.*)\s*$",
+    re.IGNORECASE,
+)
+
+
+def normalise_check_output(text: str) -> str:
+    """Strip ANSI, path directories, numbers (durations, line numbers,
+    timestamps) and collapse whitespace so two runs of the same check with
+    the same *meaning* compare equal."""
+    text = _ANSI_RE.sub("", str(text or ""))
+    text = _PATH_DIR_RE.sub("", text)
+    text = _NUM_RE.sub("N", text)
+    return text
+
+
+def failure_signature(output: str) -> frozenset[str]:
+    """The set of normalised failure lines of a build/test output.
+
+    Recognises pytest ("FAILED …", "AssertionError", "Error"), tsc
+    ("error TSNNNN"), jest ("✕", "●") and generic "FAIL"/"error" lines.
+    Count-style summary lines ("3 failed, 2 passed") are ignored so the set
+    reflects WHICH things fail, not how many the runner counted. A failed
+    run with no recognisable failure line falls back to its last non-empty
+    line so it still has a comparable identity."""
+    lines: set[str] = set()
+    last_nonempty = ""
+    for raw in normalise_check_output(output).splitlines():
+        line = _WS_RE.sub(" ", raw).strip()
+        if not line:
+            continue
+        last_nonempty = line
+        if line.startswith(("[exit code", "<UNTRUSTED_DATA", "</UNTRUSTED_DATA")):
+            # loop bookkeeping / the tool-result wrapper (whose `source=`
+            # attribute echoes the command) — not part of the check's output
+            continue
+        if _NOISE_LINE_RE.match(line):
+            continue
+        if _FAILURE_LINE_RE.search(line):
+            lines.add(line)
+    if not lines and last_nonempty:
+        lines.add(last_nonempty)
+    return frozenset(lines)
+
+
+@dataclass
+class PlateauTracker:
+    nudge_after: int = PLATEAU_NUDGE_AFTER
+    stop_after: int = PLATEAU_STOP_AFTER
+    grace_rounds: int = PLATEAU_GRACE_ROUNDS
+    pass_window: int = PLATEAU_PASS_WINDOW
+    finish_rounds: int = PLATEAU_FINISH_ROUNDS
+    no_progress_rounds: int = 0
+    total_no_progress: int = 0
+    nudged: bool = False
+    finish_nudged: bool = False
+    # Outcome of the most recent build/test this turn (None = none yet).
+    last_build_passed: bool | None = None
+    # Rounds since the most recent PASSING check (None = none this turn).
+    rounds_since_pass: int | None = None
+    # Failure-set tracking for the "debugging loop" progress signal.
+    last_failure_sig: frozenset[str] | None = None
+    seen_failure_sigs: set[frozenset[str]] = field(default_factory=set)
+    progress_log: list[str] = field(default_factory=list)
+
+    # ── progress classification ──────────────────────────────────────────
+    def round_made_progress(
+        self,
+        *,
+        changed_new_file: bool,
+        build_outcomes: list[bool],
+        todos_before: tuple[int, int],
+        todos_after: tuple[int, int],
+        build_outputs: list[str] | None = None,
+    ) -> bool:
+        """Classify one round. Also advances `last_build_passed` and the
+        failure-signature history. `build_outputs`, when given, is parallel
+        to `build_outcomes` (the raw output of each check)."""
+        progress = False
+        if changed_new_file:
+            progress = True
+            self.progress_log.append("new_file")
+        outputs = list(build_outputs or [])
+        for i, passed in enumerate(build_outcomes):
+            if passed:
+                if not self.last_build_passed:
+                    # first pass this turn, or a pass after a failure
+                    progress = True
+                    self.progress_log.append("build_pass")
+                self.rounds_since_pass = 0
+                # a pass is an empty failure set: the next failure compares to it
+                self.last_failure_sig = frozenset()
+            else:
+                out = outputs[i] if i < len(outputs) else ""
+                sig = failure_signature(out)
+                prev = self.last_failure_sig
+                if prev is not None and len(sig) < len(prev):
+                    progress = True
+                    self.progress_log.append("failures_shrank")
+                elif prev is not None and sig != prev and sig not in self.seen_failure_sigs:
+                    progress = True
+                    self.progress_log.append("new_failure_set")
+                self.seen_failure_sigs.add(sig)
+                self.last_failure_sig = sig
+            self.last_build_passed = passed
+        open_before, done_before = todos_before
+        open_after, done_after = todos_after
+        if done_after > done_before or (open_before > 0 and open_after == 0):
+            progress = True
+            self.progress_log.append("todo_completed")
+        return progress
+
+    def recent_pass(self) -> bool:
+        """True if a check passed in this round or the last `pass_window`."""
+        return self.rounds_since_pass is not None and self.rounds_since_pass <= self.pass_window
+
+    def observe_round(
+        self,
+        *,
+        round_idx: int,
+        changed_new_file: bool,
+        build_outcomes: list[bool],
+        todos_before: tuple[int, int],
+        todos_after: tuple[int, int],
+        build_outputs: list[str] | None = None,
+    ) -> str:
+        """Feed one finished tool round. Returns "" (nothing to do),
+        "wrap_up" (inject the wrap-up nudge), "finish_now" (a check just
+        passed — tell the model to finish instead of stopping it) or
+        "exhausted" (end the turn)."""
+        # Age the last pass BEFORE classifying so a pass in this round is 0.
+        if self.rounds_since_pass is not None:
+            self.rounds_since_pass += 1
+        if self.round_made_progress(
+            changed_new_file=changed_new_file,
+            build_outcomes=build_outcomes,
+            build_outputs=build_outputs,
+            todos_before=todos_before,
+            todos_after=todos_after,
+        ):
+            self.no_progress_rounds = 0
+            return ""
+        self.no_progress_rounds += 1
+        self.total_no_progress += 1
+        if round_idx < self.grace_rounds:
+            return ""
+        if not self.nudged:
+            if self.no_progress_rounds < self.nudge_after:
+                return ""
+            self.nudged = True
+            self.no_progress_rounds = 0
+            return "wrap_up"
+        if self.no_progress_rounds < self.stop_after:
+            return ""
+        if self.recent_pass():
+            # Never end a turn right after a passing check: the model may be
+            # one write away from the deliverable. Say so once, grant a few
+            # rounds; if the pass is still fresh at the next threshold, keep
+            # waiting rather than cutting off a finishing model.
+            if not self.finish_nudged:
+                self.finish_nudged = True
+                # exactly `finish_rounds` more no-progress rounds before the
+                # next threshold (may go negative when stop_after is small)
+                self.no_progress_rounds = self.stop_after - self.finish_rounds
+                return "finish_now"
+            return ""
+        return "exhausted"
+
+    # ── text ─────────────────────────────────────────────────────────────
+    @staticmethod
+    def _open_items(open_todos: list[str] | None) -> str:
+        items = [str(t).strip() for t in (open_todos or []) if str(t).strip()]
+        if not items:
+            return ""
+        shown = items[:8]
+        bullets = "\n".join(f"- {t}" for t in shown)
+        more = "" if len(items) <= 8 else f"\n- … (+{len(items) - 8} more)"
+        return f"Open plan items:\n{bullets}{more}"
+
+    def wrap_up_nudge(self, open_todos: list[str] | None = None) -> str:
+        items = self._open_items(open_todos)
+        deliverables = (
+            "(1) write every open plan item below that does not exist yet, "
+            "using the best approach you have"
+            if items
+            else "(1) write every deliverable the user named that does not exist "
+            "yet, using the best approach you have"
+        )
+        text = (
+            f"SYSTEM: No new progress for {self.nudge_after} steps — you have "
+            "reached the limit of this approach. Stop experimenting. Now: "
+            f"{deliverables}; (2) where a requirement "
+            "cannot be met, say so explicitly in the deliverable or README "
+            "instead of retrying; (3) run the project's own check ONCE; "
+            "(4) finish."
+        )
+        if items:
+            text += "\n" + items
+        return text
+
+    def finish_now_nudge(self) -> str:
+        return (
+            "SYSTEM: Your check passed — finish now: write any remaining "
+            "deliverable and stop."
+        )
+
+    def exhausted_summary(self, *, changed_files: list[str], open_todos: list[str]) -> str:
+        delivered = (
+            "Delivered (files changed this turn): " + ", ".join(f"`{p}`" for p in changed_files[:20])
+            + ("" if len(changed_files) <= 20 else f" (+{len(changed_files) - 20} more)")
+            if changed_files
+            else "Delivered: no files were changed this turn."
+        )
+        items = self._open_items(open_todos)
+        if items:
+            not_done = "Not finished. " + items
+        else:
+            not_done = (
+                "Not finished: any remaining requirements the model did not write "
+                "out — check the deliverables above against the request."
+            )
+        return (
+            "LocalCode stopped this turn: the model made no new progress for "
+            f"{self.total_no_progress} steps (kept re-editing the same files and "
+            "re-running the same checks) and did not wrap up when asked. The "
+            f"task is incomplete.\n\n{delivered}\n{not_done}"
+        )

localcode/agent/project_check_gate.py

@@ -0,0 +1,91 @@
+"""Turn-level state for the project-typecheck completion gate.
+
+The gate has to answer one question honestly: *did a checker actually prove this
+project builds?* Three states, not two — green, red, and NEVER ANSWERED. The
+third is the dangerous one: a timeout, a checker that could not execute, or a
+TypeScript reference graph that was only partially covered all used to look
+exactly like green.
+
+Kept out of `loop.py` because the decision spans the whole turn (a failure in
+round 3 must still block completion in round 6) and because the loop itself has
+no test seam — this does.
+"""
+from __future__ import annotations
+
+from ..tools.project_check import CheckOutcome
+
+__all__ = ["ProjectCheckGate", "RED", "UNVERIFIED", "OK"]
+
+# What the caller should do with the round.
+RED = "red"                  # real diagnostics — feed them back
+UNVERIFIED = "unverified"    # no verdict — retry, then block completion
+OK = "ok"                    # a checker ran green, or none was applicable
+
+
+class ProjectCheckGate:
+    """Remembers, for the whole turn, whether the project check ever answered."""
+
+    def __init__(self, max_retries: int = 2) -> None:
+        self.max_retries = max_retries
+        self.unverified = ""
+        self.red = ""
+        self.retries = 0
+
+    def observe(self, outcome: CheckOutcome) -> str:
+        """Record a completed check. Returns RED / UNVERIFIED / OK."""
+        if outcome.is_red:
+            # Red is a verdict: the checker worked. Clear any earlier no-verdict.
+            self.unverified = ""
+            # ...but REMEMBER it. The loop feeds the diagnostics back and asks
+            # for a fix, and that nudge is bounded so an unfixable project can't
+            # spin. Running out of nudges is not the project turning green: it
+            # used to drop the red on the floor and let the turn complete as
+            # verified with a broken build. Same rule the no-verdict path
+            # already states, applied to the verdict we actually have.
+            self.red = outcome.detail or outcome.label or "the project typecheck reported errors"
+            return RED
+        if outcome.status in ("timed_out", "failed"):
+            self.unverified = outcome.detail or outcome.status
+            return UNVERIFIED
+        # Only a checker that actually ran to GREEN clears an earlier verdict.
+        # `unavailable` reaches here too, and must NOT: "no checker available"
+        # is the absence of evidence, so treating it as clearing would let a
+        # project that went red in round 2 launder itself clean in round 3 the
+        # moment the checker stopped being detectable (node_modules removed
+        # mid-turn, a tsconfig edited into an unparseable state).
+        if outcome.is_verified:
+            self.unverified = ""
+            self.red = ""
+        return OK
+
+    def observe_exception(self, exc: BaseException) -> str:
+        """An unexpected failure is a FAILED verification, never a clean one."""
+        self.unverified = (
+            f"the project typecheck could not be run ({exc.__class__.__name__})")
+        return UNVERIFIED
+
+    def consume_retry(self) -> bool:
+        """True if another round should be forced. Bounded, so an unfixable
+        environment can't spin — but running out of retries does NOT make the
+        project verified; `blocks_completion` stays True."""
+        if self.retries >= self.max_retries:
+            return False
+        self.retries += 1
+        return True
+
+    def blocks_completion(self) -> bool:
+        """A check that never returned a verdict — or that returned errors
+        nobody fixed — is not evidence of a working build, whatever else the
+        verification registry happens to hold."""
+        return bool(self.unverified or self.red)
+
+    def result_note(self) -> str:
+        """Text for the FINAL RESULT, so the reason reaches the TUI and `--json`
+        (unlike print_info, which is invisible in the TUI and suppressed under
+        --json)."""
+        if self.unverified:
+            return f"\n\nProject typecheck was not verified: {self.unverified}"
+        if self.red:
+            return ("\n\nThe project typecheck is still reporting errors:\n"
+                    f"{self.red}")
+        return ""

localcode/agent/prompt_context.py

@@ -0,0 +1,264 @@
+"""Prompt assembly helpers for the agent loop."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .prompts import (
+    REASONING_RULES,
+    SYSTEM_PROMPT,
+    _load_project_instructions,
+    model_identity_line,
+    project_stack_line,
+)
+from .sections import Section, SectionContext, compose_system_prompt, default_sections
+__all__ = [
+    "PromptBuildResult",
+    "build_agent_system_prompt",
+    "build_task_goal_block",
+    "build_dynamic_skills_block",
+    "build_target_grounding_block",
+    "build_incremental_milestones_block",
+]
+
+
+@dataclass
+class PromptBuildResult:
+    system_prompt: str
+    selected_skills: list[str]
+    selected_skill_origins: list[str]
+    selected_skill_chars: int
+    skill_candidates: list[dict[str, str]]
+
+
+def build_agent_system_prompt(
+    *,
+    app: Any,
+    user_text: str,
+    goal_state: Any,
+    task_state: Any,
+    base_system_prompt: str,
+    network_status: str,
+    use_thinking: bool,
+) -> PromptBuildResult:
+    project_instructions = _load_project_instructions(app.repo_root)
+    task_goal_block = build_task_goal_block(user_text, goal_state, task_state)
+    target_grounding_block = build_target_grounding_block(app.repo_root, goal_state)
+    milestones_block = build_incremental_milestones_block(goal_state)
+    skills_block, skill_names, skill_origins, skill_chars, skill_candidates = (
+        build_dynamic_skills_block(app, user_text)
+    )
+    # Tell the model which local model/quant it's actually running on, so
+    # "which model are you using?" gets a correct answer instead of a guess.
+    # Derived per-session from the active model (config.runtime.model →
+    # catalog friendly name + quant). Folded into the front of the
+    # network_status slot so it renders right after the "Working directory"
+    # line, with no change to the section registry. Empty when no model is
+    # configured (keeps the prompt prefix byte-identical for that case).
+    identity_line = ""
+    try:
+        identity_line = model_identity_line(str(app.config.runtime.model or ""))
+    except Exception:
+        identity_line = ""
+    # Name the detected project stack (one line) so the model writes code
+    # in the project's actual language/conventions instead of falling back
+    # to Python idioms. Cheap, marker-file based, and best-effort: any
+    # failure leaves the slot empty so the cached prefix is unaffected.
+    stack_line = ""
+    try:
+        stack_line = project_stack_line(app.repo_root)
+    except Exception:
+        stack_line = ""
+    network_status_with_identity = identity_line + stack_line + network_status
+
+    def _render_caller_template(ctx: SectionContext) -> str:
+        return base_system_prompt.format(
+            cwd=ctx.cwd,
+            project_instructions=ctx.project_instructions,
+            network_status=ctx.network_status,
+            skills_block=ctx.skills_block,
+            reasoning_rules=ctx.reasoning_rules,
+        )
+
+    section_ctx = SectionContext(
+        cwd=app.repo_root,
+        project_instructions=project_instructions,
+        network_status=network_status_with_identity,
+        skills_block=skills_block,
+        reasoning_rules=REASONING_RULES if use_thinking else "",
+    )
+    using_default_prompt = base_system_prompt == SYSTEM_PROMPT
+    system = compose_system_prompt(
+        section_ctx,
+        sections=default_sections()
+        if using_default_prompt
+        else [Section(id="caller_template", render=_render_caller_template, cacheable=False)],
+        emit_cache_marker=using_default_prompt,
+    )
+    return PromptBuildResult(
+        system_prompt=system + task_goal_block + target_grounding_block + milestones_block,
+        selected_skills=skill_names,
+        selected_skill_origins=skill_origins,
+        selected_skill_chars=skill_chars,
+        skill_candidates=skill_candidates,
+    )
+
+
+def build_target_grounding_block(repo_root: Any, goal_state: Any) -> str:
+    """One short block that pins the target directory for build-type turns.
+
+    Grounds the model so it stops thrashing between the repo root and a subdir.
+    Returned only for build_app-shaped goals; empty otherwise so the cached
+    prompt prefix is unaffected for ordinary turns.
+    """
+    goal_type = str(getattr(goal_state, "goal_type", "") or "")
+    if goal_type != "build_app":
+        return ""
+    try:
+        root = str(Path(repo_root).resolve())
+    except Exception:
+        root = str(repo_root or "")
+    if not root:
+        return ""
+    # Don't anchor to $HOME. When localcode is launched outside any project
+    # (no .git/package.json/etc. marker found), repo_root falls back to the
+    # user's home dir. Telling the model "the project root is /Users/<name>,
+    # create all files under that root" then makes it try to build in $HOME —
+    # or conflict with the path the user actually named in the task ("work at
+    # root vs. the Anki/... path they gave"). In that unanchored case, emit no
+    # directive and let the model follow the location from the user's request.
+    try:
+        if Path(root) == Path.home():
+            return ""
+    except Exception:
+        pass
+    return (
+        "\n\nTarget location (work here, do not drift):\n"
+        f"- The project root is: {root}\n"
+        "- Create and edit all files under that root. Do not switch between the "
+        "root and an unrelated subdirectory between steps; decide once and stay there.\n"
+    )
+
+
+def build_incremental_milestones_block(goal_state: Any) -> str:
+    """Lightweight guidance to build a large app in verifiable milestones.
+
+    For a build_app goal, instruct the model to make incremental, verified
+    progress — scaffold first, then one feature at a time, building/running
+    between steps — instead of emitting an entire app in a single giant
+    write (which is what hits the per-round token wall and lands unverified
+    code). This is intentionally a prompt-context guidance block rather than
+    a mechanism: cheap, no per-round bookkeeping, and the build-verification
+    nudge in the loop already enforces the "build before finishing" half.
+
+    Empty for non-build_app goals so the cached prompt prefix is unaffected.
+    """
+    goal_type = str(getattr(goal_state, "goal_type", "") or "")
+    if goal_type != "build_app":
+        return ""
+    return (
+        "\n\nBuild in verifiable milestones (do not emit the whole app at once):\n"
+        "1. SCAFFOLD: create the minimal runnable skeleton first — entrypoint, "
+        "project/config file, and a placeholder that starts. Run it to confirm "
+        "it launches before adding features.\n"
+        "2. ONE FEATURE AT A TIME: add a single feature per step, in small files. "
+        "After each feature, build/typecheck or run the relevant check and FIX "
+        "any error before moving to the next.\n"
+        "3. KEEP IT RUNNABLE: never leave the project in a broken state between "
+        "steps. If a step is too large for one tool call, split it across calls; "
+        "don't drop scope.\n"
+        "4. FINISH: only report done after a final build/run passes with no "
+        "errors. Don't claim it works without having run it.\n"
+    )
+
+
+def build_task_goal_block(user_text: str, goal_state: Any, task_state: Any) -> str:
+    # The general agentic goal block ("Current goal: X / Continue until
+    # complete and verified" plus stage guidance, port hints, build_app
+    # phase ladder, user-requested-features checklist) was removed
+    # 2026-04-29. None of it measurably prevented the failures it was
+    # added to mitigate (loops, over-verification, premature stops on
+    # Qwen3.6 IQ2_M); mainstream agentic CLIs don't do it; and the
+    # "Continue until complete" framing actively pushed the model into
+    # eager exploration on trivial inputs ("hi" → list_files + 3× read
+    # README). Only one piece survived: the question-type protective
+    # wording, which has a regression test and prevents auto-resume of
+    # a prior failed/blocked task on a clarifying question.
+    if goal_state.goal_type == "question":
+        block = (
+            "\n\nCurrent goal:\n"
+            f"- Answer this question directly: {user_text.strip()}\n"
+            "- This is a question/diagnostic turn, not permission to resume prior coding work.\n"
+            "- Do not continue, rebuild, edit, launch, or verify a previous task unless the user explicitly asks you to do that.\n"
+            "- If local evidence is needed, inspect only the smallest relevant files/logs, then answer.\n"
+        )
+        if task_state is not None:
+            status = getattr(task_state, "status", "") or ""
+            slug = getattr(task_state, "task_slug", "") or ""
+            if status or slug:
+                block += f"- Previous task context: {slug or 'task'} status={status or 'unknown'}.\n"
+        return block
+    return ""
+
+
+def build_dynamic_skills_block(
+    app: Any,
+    user_text: str,
+) -> tuple[str, list[str], list[str], int, list[dict[str, str]]]:
+    try:
+        from ..skills import (
+            dynamic_skill_block,
+            dynamic_skill_candidates,
+            load_registry,
+            select_dynamic_skills,
+        )
+
+        registry = load_registry(app.repo_root)
+        catalog = registry.listing()
+        catalog_block = (
+            "\n\n## Available Skills\n"
+            "Load a matching recipe with the skill tool; full bodies are deferred.\n"
+            + catalog
+            if catalog else ""
+        )
+        recent_tools = list(getattr(app, "_recent_tool_names", []) or [])
+        last_failed_tool = str(getattr(app, "_last_failed_tool_name", "") or "")
+        candidates = dynamic_skill_candidates(
+            user_text,
+            recent_tools=recent_tools,
+            last_failed_tool=last_failed_tool,
+        )
+        selected = select_dynamic_skills(
+            user_text,
+            registry,
+            recent_tools=recent_tools,
+            last_failed_tool=last_failed_tool,
+        )
+        # Gate on selected count rather than letting dynamic_skill_block
+        # return its own placeholder/header for an empty list. With no
+        # selected skills (the steady-state today: events show
+        # selected_count=0 every turn), the prompt template's
+        # {skills_block} slot becomes an empty string — saves a few
+        # hundred bytes of header/scaffolding per round and, more
+        # importantly, keeps the prompt prefix byte-identical to other
+        # turns so llama.cpp's prefix-cache can hit.
+        if not selected:
+            return (
+                catalog_block,
+                [],
+                [],
+                0,
+                candidates,
+            )
+        block = catalog_block + dynamic_skill_block(selected)
+        return (
+            block,
+            [skill.name for skill in selected],
+            [skill.origin for skill in selected],
+            len(block),
+            candidates,
+        )
+    except Exception:
+        return "", [], [], 0, []