Roles, capability profiles and help on the new loop (M2.6)

- roles.driver (unset: the planner's model) and roles.classifier (unset:
  the expert's); the mapping is pinned when an item opens, and the driver
  and the go-ahead reader run on the item's own (L9).
- profiles: in configuration (tools, strengths, weaknesses), used in
  briefings: the driver's instructions say what its helper and expert are
  good at, the helper's brief who reads its handback; never a model name.
- delegate(task) and ask_expert(question) for the driver. A helper works
  on a branch off the milestone's; on a handback its work comes back as
  uncommitted changes, otherwise it is discarded, so harness branches
  never hold commits only the clone has. ask_expert keeps its budget.
- Triggers: failure_limit failed commands in a row (Driver's new "stuck"
  outcome) or the turn cap, mid-milestone, call a helper in once per
  milestone; if it fails too, the item waits on the operator. A
  delegation cut off by a crash is discarded at boot.
- Evaluation capture: delegations and ask_expert as before, and the
  reader's verdicts as classifier pairs.

Tests: help tests (merge-back, discard, needs a milestone, the stuck
trigger and its once-per-milestone limit, the expert and its budget,
pinning, briefings by profile, boot discarding a cut-off delegation),
config tests for roles and profiles, and the walk delegating with a
scripted helper that sometimes fails, with a delegations_settle property.
The walk found helper commits stranded on a merged PR's branch, fixed by
returning a helper's work uncommitted.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PPQ14L3LikyefCMFBqEbKE

nisse-dev/src/nisse_dev/loop/agent.py

@@ -15,6 +15,7 @@ a message is recorded and changes its item's state, but never interrupts a
 run (L1).
 """
 
+import contextlib
 import re
 import threading
 import time
@@ -23,12 +24,22 @@ from collections.abc import Callable, Iterable, Sequence
 from dataclasses import dataclass, replace
 
 from nisse_dev.cancel import Cancel
-from nisse_dev.canonical import Fact, PlanSubmitted, UserMessage
+from nisse_dev.canonical import (
+    DelegationCompleted,
+    DelegationStarted,
+    Fact,
+    PlanSubmitted,
+    UserMessage,
+)
 from nisse_dev.config import GENERAL
+from nisse_dev.delegation import DELEGATION_INTENT, Delegation
+from nisse_dev.expert import BudgetExhausted, ExpertDesk
 from nisse_dev.gates import command_form
 from nisse_dev.git import GitError
 from nisse_dev.gitea import GiteaClient, GiteaError, Issue
+from nisse_dev.llm import LLMError, RoleMap
 from nisse_dev.loop.driver import Driver, RunOutcome
+from nisse_dev.loop.help import ASK_EXPERT, DELEGATE, Helpers
 from nisse_dev.loop.items import (
     ANSWER,
     BLOCKED,
@@ -118,7 +129,7 @@ edge cases, and the tests that are its acceptance criteria. Commit it with the
 first milestone, and mark each milestone done in it in that milestone's PR.
 Keep ARCHITECTURE.md current: a design change updates it in the same PR.
 
-{labels}Never label the issue yourself; you may suggest a label to the operator.
+{labels}{helpers}Never label the issue yourself; you may suggest a label to the operator.
 
 {workspace}"""
 
@@ -212,6 +223,7 @@ class LoopAgent:
         # A new project's entry, once the operator has added it (D1, D8):
         # the projects configured now that this agent doesn't know yet.
         reload: Callable[[set[str]], Sequence[Project]] | None = None,
+        helpers: Helpers | None = None,
         clock: Callable[[], float] = time.time,
         intake_interval_s: float = INTAKE_INTERVAL_S,
     ) -> None:
@@ -233,6 +245,7 @@ class LoopAgent:
         self._grace = bug_grace_s
         self._idle = general_idle_s
         self._reload = reload
+        self._helpers = helpers
         self._clock = clock
         self._interval = intake_interval_s
         # thread root -> revision on screen there, read on the transport's
@@ -318,6 +331,7 @@ class LoopAgent:
         self._store.set_active(None, cause="boot")
         self._reconcile_publishing()
         self._reconcile_filing()
+        self._reconcile_delegations()
         for item in self._store.work_items("open"):
             loop = loop_of(item)
             self._threads[(item.scope or "", loop.issue)] = loop.thread
@@ -338,6 +352,30 @@ class LoopAgent:
                         thread=loop.thread,
                     )
 
+    def _reconcile_delegations(self) -> None:
+        """L8, L9: a delegation cut off by a crash is discarded, its branch
+        deleted and the milestone's left as it was. The item, cut off mid-
+        run, then waits on the operator like any other."""
+        for intent in self._store.pending_intents():
+            if intent.kind != DELEGATION_INTENT or not intent.work_item:
+                continue
+            item = self._store.work_item(intent.work_item)
+            branch = str(intent.payload.get("branch", ""))
+            base = str(intent.payload.get("base", ""))
+            project = self._projects.get(item.scope or "") if item else None
+            milestones = project.milestones if project else None
+            if milestones is not None and branch and base:
+                with contextlib.suppress(GitError):
+                    milestones.git.reset_to(base, base)
+                with contextlib.suppress(GitError):
+                    milestones.git._git("branch", "-q", "-D", branch)
+            self._store.abort_intent(intent.id, cause="cut off by a restart")
+            if item is not None:
+                self._fact(
+                    item,
+                    f"a helper's work on {branch} was cut off by a restart and discarded",
+                )
+
     def _reconcile_filing(self) -> None:
         """L8: a record issue cut off by a crash. An issue carrying the new
         item's ID was opened: its item is started now. Otherwise nothing was
@@ -1096,7 +1134,30 @@ class LoopAgent:
             for e in self._store.transcript(item.id, "driver").read()
             if isinstance(e.event, PlanSubmitted)
         ]
-        return bool(proposals) and self._reader.agrees(proposals[-1], text)
+        if not proposals:
+            return False
+        classifier = self._roles_of(item).resolve("classifier")
+        agreed = self._reader.agrees(proposals[-1], text, model=classifier)
+        # L9 evaluation capture: the reading, as an input/output pair.
+        log = self._store.transcript(item.id, "classifier")
+        log.append(
+            DelegationStarted(
+                brief=f"proposal:\n{proposals[-1]}\n\nreply:\n{text}",
+                role="classifier",
+                model=classifier,
+                caps={},
+            )
+        )
+        log.append(
+            DelegationCompleted(
+                handback="a go-ahead" if agreed else "not a go-ahead",
+                artifacts=[],
+                tokens=0,
+                duration_s=0.0,
+                exit_status="answered",
+            )
+        )
+        return agreed
 
     def _which(self, command: str) -> str:
         """L5: an unnamed command at top level is ambiguous: ask."""
@@ -1217,6 +1278,160 @@ class LoopAgent:
                 )
         self._last_project = here
 
+    # -- help (L9) -------------------------------------------------------------
+
+    def _roles_of(self, item: WorkItem) -> RoleMap:
+        """The roles pinned when the item opened, so a configuration change
+        never splits one item across models (L9)."""
+        default = (
+            self._helpers.roles
+            if self._helpers
+            else RoleMap(
+                executor="",
+                planner=self._roles.get("planner", ""),
+                helper="",
+                expert="",
+            )
+        )
+        pinned = item.data.get("roles") or self._roles
+        return RoleMap.from_pinned(dict(pinned), default)
+
+    def _delegate(
+        self, item_id: str, task: str, *, trigger: str = ""
+    ) -> tuple[str, bool]:
+        """A helper takes a sub-task on a branch off the milestone's: merged
+        back on a handback, discarded otherwise."""
+        item = self._store.work_item(item_id)
+        assert item is not None
+        loop = loop_of(item)
+        milestones = self._at(item).milestones
+        workspace = self._at(item).workspace
+        if self._helpers is None or milestones is None or workspace is None:
+            return "there's no helper here", False
+        if not loop.branch:
+            return "start a milestone first: a helper works on its branch", False
+        if not task:
+            return "say what the sub-task is", False
+        roles = self._roles_of(item)
+        number = loop.helps + 1
+        branch = f"{loop.branch}-help-{number}"
+        save(
+            self._store,
+            item.id,
+            item.position,
+            replace(loop, helps=number),
+            cause=f"helper {number} called in",
+        )
+        helper = roles.resolve("helper")
+        delegation = Delegation(
+            self._helpers.delegate_client(helper),
+            self._store,
+            workspace,
+            milestones.git,
+            model=helper,
+            caps=self._helpers.caps,
+            cancel=self._cancel,
+            reader=self._helpers.reader(roles),
+        )
+        git = milestones.git
+        before = git.head_sha()  # where the milestone is, uncommitted work aside
+        brief = (
+            f'{task}\n\nThe work item: issue #{loop.issue}, "{item.title}", '
+            f"milestone {loop.milestone}." + (f" {trigger}" if trigger else "")
+        )
+        result = delegation.run(
+            self._store.transcript(item.id, "helper"), brief=brief, branch=branch
+        )
+        try:
+            # The milestone takes the helper's work (or, on failure, only
+            # its own back) as uncommitted changes: harness branches never
+            # hold commits only this clone has (publishing makes them), so
+            # parking, a later milestone and a follow-up PR all carry it.
+            git.reset_to(loop.branch, branch if result.usable else loop.branch)
+            git._git("reset", "-q", "--soft", before)
+            if branch in git.local_branches():
+                git._git("branch", "-q", "-D", branch)
+        except GitError as exc:
+            self._fact(item, f"after helper {number}: {exc}")
+        for intent in self._store.pending_intents():
+            # Cut off rather than finished: discarded all the same, never
+            # resumed blindly (L8, L9).
+            if (
+                intent.kind == DELEGATION_INTENT
+                and intent.payload.get("branch") == branch
+            ):
+                self._store.abort_intent(intent.id, cause=f"delegation {result.status}")
+        if result.usable and result.handback is not None:
+            self._fact(item, f"helper {number} finished: {result.handback.render()}")
+            return f"the helper finished:\n{result.handback.render()}", True
+        self._fact(
+            item, f"helper {number} didn't finish ({result.status}): {result.note}"
+        )
+        said = (
+            f"the helper didn't finish ({result.status}: {result.note}); its work "
+            "was discarded and the milestone is as it was"
+        )
+        return said, False
+
+    def _ask_expert(self, item_id: str, question: str) -> tuple[str, bool]:
+        item = self._store.work_item(item_id)
+        assert item is not None
+        if self._helpers is None:
+            return "there's no expert here", False
+        if not question:
+            return "ask a question", False
+        desk = ExpertDesk(
+            self._helpers.client,
+            self._roles_of(item),
+            budget=self._helpers.expert_budget,
+        )
+        try:
+            answer = desk.ask(self._store.transcript(item.id, "expert"), question)
+        except BudgetExhausted as exc:
+            return str(exc), False
+        except LLMError as exc:
+            return f"the expert couldn't answer: {exc}", False
+        return answer.render(), True
+
+    def _help_when_stuck(self, item: WorkItem, loop: Loop, outcome: RunOutcome) -> bool:
+        """L9's observable triggers: the driver stuck (commands failing in a
+        row) or out of turns mid-milestone. A helper is called in, once per
+        milestone; True when it finished and the driver goes on."""
+        if (
+            self._helpers is None
+            or outcome.kind not in ("stuck", "capped")
+            or not loop.branch
+            or loop.helped_at == loop.milestone
+        ):
+            return False
+        save(
+            self._store,
+            item.id,
+            RUNNING,
+            replace(loop, helped_at=loop.milestone),
+            cause="helper called in",
+        )
+        self._transport.post(
+            f"I got stuck ({outcome.note[:200]}), so a helper is taking over the "
+            f"rest of milestone {loop.milestone}.",
+            thread=loop.thread,
+        )
+        self._running = True
+        try:
+            _, ok = self._delegate(
+                item.id,
+                f"Finish milestone {loop.milestone}, so its tests pass.",
+                trigger=f"The driver got stuck: {outcome.note}",
+            )
+        finally:
+            self._running = False
+            self._cancel.clear()
+        if not ok:
+            return False
+        item = self._store.work_item(item.id) or item
+        save(self._store, item.id, READY, loop_of(item), cause="a helper finished")
+        return True
+
     def _design_problem(self, item_id: str) -> str | None:
         """D1, D2: a `design` item agrees its design before any code. Until
         a PR of it has merged, a milestone holds documents only."""
@@ -1340,16 +1555,23 @@ class LoopAgent:
                     FINISH_MILESTONE,
                     CLOSE_ITEM,
                     *([WAIT_FOR_REVIEW] if loop.pr else []),
+                    *([DELEGATE, ASK_EXPERT] if self._helpers else []),
                     *EXECUTOR_TOOLS,
                 ]
             ),
         ]
+        roles = self._roles_of(item)
         workspace = project.workspace
         system = SYSTEM.format(
             repo=project.repo,
             issue=loop.issue,
             title=item.title,
             labels="".join(f"{LABELS[x]}\n\n" for x in loop.labels if x in LABELS),
+            helpers=(
+                f"{self._helpers.briefing(roles)}\n\n"
+                if self._helpers and loop.started
+                else ""
+            ),
             workspace=workspace.describe() if workspace else "",
         )
         self._active_thread = loop.thread
@@ -1360,11 +1582,20 @@ class LoopAgent:
                 system=system,
                 tools=tools,
                 workspace=workspace,
-                handlers={"start_milestone": lambda args: self._start(item.id, args)},
+                handlers={
+                    "start_milestone": lambda args: self._start(item.id, args),
+                    "delegate": lambda args: self._delegate(
+                        item.id, str(args.get("task", "")).strip()
+                    ),
+                    "ask_expert": lambda args: self._ask_expert(
+                        item.id, str(args.get("question", "")).strip()
+                    ),
+                },
                 checks={
                     "restate": _restatement_problem,
                     "finish_milestone": lambda args: self._design_problem(item.id),
                 },
+                model=roles.resolve("driver"),
             )
         finally:
             self._running = False
@@ -1505,6 +1736,8 @@ class LoopAgent:
         elif outcome.kind == "stopped":
             note = f"stopped ({outcome.note}). Why did you stop it? Reply to continue."
             self._wait(item, replace(loop, wait=ANSWER, note=note), note)
+        elif self._help_when_stuck(item, loop, outcome):
+            pass  # ready again: the driver goes on from the helper's handback
         else:
             note = f"I stopped short: {outcome.note}. Reply to continue."
             self._wait(item, replace(loop, wait=ANSWER, note=note), note)