## Summary #469 gave a bundled sub-agent nine verbs in place of six hook phases. Reviewing it turned up a list of things the contract said but did not yet do, and this PR closes that list. No behaviour change is intended: the point is that the same seam becomes something a role can replace and something a generated judgement can enter. **1. The roles are named apart from the verbs, and `observe` is gone.** `ActionModule.review` and the participant's `review` were two different things a line apart. The four delegating role methods now say what they do -- they ask -- and the verbs keep their own names, so `ask_review` asks `review`. `observe` is removed: a verb with no return value decides nothing and can only keep state a participant is forbidden to keep. `outbound` says on its own docstring that it is the one verb with no role seat, and `StepView` gains `phase`, so a verb asked at two moments reads which one it is rather than inferring it from whichever other field happens to be set (`tools_ran` becomes a property derived from it, so the two cannot disagree). **2. The three verbs the seat was applying itself get a seat.** `system_addendum`, `archive` and `select_tools` were rendered straight onto the hook decision, so each was the one judgement in the set with nowhere to compose two participants, nowhere to vet what came back, and nothing a replacement role could decide. They join the other four: `MemoryModule.ask_system_addendum` / `ask_archive` and `CapabilityModule.ask_select_tools`. The seat is not the point where narrowing takes effect -- `select` still is, and the registry still adjudicates every call -- so a participant narrows after the product has spoken and never instead of it. **3. A participant answers with plain data.** `review`, `intake` and `system_addendum` returned host classes (`Verdict`, `Intake`) and `salvage` returned `Any`. `Accept`, `Resample`, `End` and `Intake` are now builders returning plain mappings, the host reads one back with `read_verdict` / `read_intake`, and an answer it cannot read is silence rather than a refusal. That is what makes the third invariant real and what lets a judgement compiled from source answer the same verbs a plugin does -- it can build a `dict`; it cannot build a host class. **4. A dispatch's judgements are a participant.** `judge` was the one verb a role answered by reading the dispatch's own `checks` and `code` for itself. A Charter now enters as a participant like any other, `ActionModule.ask_judge` takes the list, and the merge is a veto so the first refusal decides. The participant list becomes the only route an external judgement takes, which is the thing step four needs: a judgement generated for one dispatch joins the same list without a second way in. **5. The rename.** `AgentConduct` is `AgentParticipant`, `contracts/agent_conduct.py` is `contracts/participant.py`, `agent/hook/conduct.py` is `agent/hook/participant.py`, and `agent/harness/conducts.py` is `agent/harness/participants.py`. "Conduct" was already taken in this tree -- raven-code's Coding Conduct prompts are a different thing -- and a reader hitting both had no way to tell them apart. The rename was done symbol by symbol, not by search and replace, for exactly that reason. **7. Review (LivXue, at 3a1bf07c).** The `judge` disclosure had reached two of its four homes; the other two are `ActionModule.ask_judge` on the paper and `DefaultAction.ask_judge`, and they survived because they phrase the claim without naming any symbol the earlier fix touched. The test meant to pin that claim could not fail for the reason it was written -- it asserted the refusal rather than the argument, and built a `ParticipantHook` it dropped -- and now asserts what the registry hands the role, mutation-checked by wiring a participant through. `compose_judge` exploded a one-sentence `str` refusal into one refusal per character, because `str` satisfies `Sequence[str]` structurally; `charter_code.run_judge` coerced it where this composition used to live and the handling did not move with it. Two records corrected: the type-only `raven.contracts` -> `raven.agent` edge, the first in the tree and the price of moving `Verdict` and `Intake` off the paper, is now written beside the import contract it bends rather than left to be discovered; and the ledger entry for the 3,200 -> 3,410 bump is restored to the names and count it was written with. Not taken: reading `step.phase` at `research_flow/flow.py:1000` -- the gate chain's phase vocabulary and `StepView.phase` coincide on `after_iteration` only, and that call site wants `before_execute_tools`, which is the key `_phase` dispatches on. **6. What the paper was claiming and not doing.** Read back over the seam afterwards rather than over the diff. ``judge`` read as though a plugin's override were asked ahead of a dispatch's own rules; it is not, and cannot be as written, because the party that asks the verb is ``ToolRegistry.execute``, which is not the hook chain and holds no handle on this turn's participants. The merge order is real; nothing puts a plugin in the list. Wiring one through is a turn-scoped register this change does not add, and it would start refusing calls that run today, so it is named on the paper and pinned by a test instead. ``max_iterations`` had lost its docstring to the property inserted between the field and the string documenting it. No executable line moves in this commit: the module's AST, docstrings stripped, is identical to its parent's. CONTEXT.md's entry is rewritten to the end state, including the two kinds of role method, the two verbs that are exceptions, and the note that the Coding Conduct prompts are unrelated. One item from the same list is deliberately not here: a `planning.*` block on the dispatch parameters. It is not a contract closeout but a new model-facing field, and it needs the generator's schema and prompt to move with it. Contract papers: `participant.py` and `harness.py` are both factory-loop tier, so the contract-tier digest and `CONTRACTS_VERSION` do not move. `CONTRACTS_LINE_CEILING` 3,440 to 3,470 to 3,500 to 3,540 to 3,550 to 3,570, each bump with its own review paragraph in `tests/test_kernel_budget.py`. The chain was recomputed after rebasing onto #410, which added seven lines to `loop_hooks.py` inside the old headroom and left one commit here with one line of it; every "Measured at" figure in that file is the count at that commit. ## Type - [ ] Fix - [ ] Feature - [ ] Docs - [ ] CI / tooling - [x] Refactor - [ ] Other ## Verification Gates, run at each of the seven commits: ``` uv run ruff check --no-cache raven evolver agents plugins-dist tests scripts uv run ruff format --check --no-cache raven evolver agents plugins-dist tests scripts uv run lint-imports uv run pytest -q npx commitlint --from origin/main --to HEAD --config commitlint.config.cjs uv run python scripts/check_commit_messages.py origin/main..HEAD uv run python scripts/check_source_language.py origin/main..HEAD uv run python scripts/check_large_files.py origin/main..HEAD ``` Import contracts: 10 kept, 0 broken. The suite is green: the failures this machine shows are the same ones it shows on an unmodified `main` in the same worktree layout (missing browser and optional packages), and this branch adds none. Behaviour preservation. The oracle is the hook seam itself. `main` and this branch were run under the same scripted provider, outputs normalised for nonces and temp paths, then byte-compared. Four scenarios, all identical: - the five-plugin hook seam, every phase's decision and metadata per iteration (23,840 bytes) - a whole turn with no playbook: host turn, spawned sub-agent, tool calls and refusals - a playbook-on worker lane in process, including the charter refusals - six window-shrink scenarios This is the seam the change is about, and identical output across it is what "no behaviour change" means here -- it is not a claim about paths the four scenarios do not reach. Two claims had no assertion anywhere and now do. ``phase``, and the ``tools_ran`` derived from it, are what three of the five bundled plugins branch on -- ppt on its close, oncall on its counter, research on which gate runs -- and a mistyped phase string at one of the six call sites would have changed what they do with a green suite. The read-only test now also covers ``mode_overlay``, the one frozen field it skipped. All three assertions were mutation-checked: mislabelling a phase, deriving ``tools_ran`` from the wrong one, and dropping the freeze each turn exactly their own test red. New tests, each written against a claim the contract now makes rather than against the code: a participant cannot write through the `StepView` it is shown; an answer the host cannot read is silence, not a refusal; a participant that answers with a mapping it built itself is understood; every verb with a seat goes through its role rather than around it, asserted as a set so a new verb that bypasses its role fails; two seats in one chain each keep one addendum; two turns in flight keep their own participants; a bound role decides what a participant's verdict does; a plugin's own judgement speaks before the dispatch's, and a silent participant lets the next one speak. Real model, Sonnet 4.5 through OpenRouter, on this branch: a query generates a playbook, two sub-agents are instantiated and run, each writes its `summary.md` under its own fence, and both results are announced back to the originating session. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed ## Risk For plugin authors: the six-phase `AgentHook` is untouched and a plugin shipping one keeps working. A plugin written against #469's `AgentConduct` needs the new names and, if it answered with `Verdict` or `Intake`, the builders instead -- the five bundled plugins are ported here and are the worked examples. One verb narrowed, and silently for a plugin that used the width. `salvage` was annotated `Any | None` and `compose_salvage` returned whatever was not None; it is now `str | None` and only a non-empty string is taken. A third-party plugin that salvages with a reply object rather than text stops being heard rather than raising -- which is the third invariant working as written, and worth knowing before upgrading. The narrowing is deliberate: `salvage` answers the text a turn sends when it produced none, and `Any` was not a contract. For anyone replacing a harness role: the four delegating methods are renamed and four more are added, so a replacement written against #469 needs them. `bind()` names the missing member at assembly rather than failing inside a turn. Rollback is a revert of the merge commit. Nothing persisted on disk changes shape. - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes ## Related Issues Follows #468 and #469. Generated with Claude Code (https://claude.com/claude-code) --------- Co-authored-by: yao pengfei <yaopengfei@shanda.com> Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
133 lines
5.9 KiB
Python
133 lines
5.9 KiB
Python
"""A tree whose hook can roll back declares it on the class the loop sees.
|
|
|
|
``AgentHook.rolls_back_iterations`` is read off the hook object the loop holds,
|
|
once per turn, before any per-session state is resolved. A hook that delegates
|
|
its phases to a per-session chain therefore cannot have the flag derived for it:
|
|
the chain does not exist yet at the moment of the read. ``ResearchFlowHook`` is
|
|
that shape -- its six rollback sites live in ``gates/``, behind a composite it
|
|
builds per session -- so the declaration is the only thing standing between a
|
|
rolled-back draft and the reader, and nothing local to ``flow.py`` hints that it
|
|
is needed. This file is that hint.
|
|
|
|
The producing set is derived rather than listed: every ``HookDecision`` built
|
|
with ``rollback=True`` is found by AST, so a tree that grows a rollback has to
|
|
appear in ``REGISTERED_HOOK`` before this file passes. AST rather than imports on
|
|
purpose -- ``raven_design`` and ``raven_ppt`` are editable installs rooted at the
|
|
main checkout, so importing them from a worktree reads the main checkout's code
|
|
instead of the revision under test.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import ast
|
|
from pathlib import Path
|
|
|
|
import pytest
|
|
|
|
REPO = Path(__file__).resolve().parent.parent
|
|
|
|
#: Tree root -> (module holding the contributed hook, its class name). The keys
|
|
#: are checked against the derived producing set, so this table cannot go quietly
|
|
#: stale: a new rollback in an unlisted tree fails as an unmapped root.
|
|
REGISTERED_HOOK: dict[str, tuple[str, str]] = {
|
|
"agents/raven-research/plugins/research-flow": ("research_flow/flow.py", "ResearchFlowHook"),
|
|
# design-engine no longer builds a rollback itself: its participant answers
|
|
# ``Resample`` and ``ParticipantHook`` renders that as the rollback, so the
|
|
# declaration lives on the adapter, once, for every participant seated in it.
|
|
# ppt-engine and oncall-flow: same shape as design-engine, their participants
|
|
# answer through the adapter, so the adapter's declaration is theirs too.
|
|
"raven/agent/hook": ("participant.py", "ParticipantHook"),
|
|
}
|
|
|
|
SEARCH_ROOTS = ("agents", "plugins-dist", "raven", "evolver")
|
|
|
|
|
|
def _rollback_producers() -> dict[Path, int]:
|
|
"""Files building ``HookDecision(rollback=True)``, mapped to a hit count.
|
|
|
|
Tests are excluded: a test fake rolls back to drive the loop and is not a
|
|
contributed hook. Docstrings naming ``rollback=True`` are not calls and so
|
|
never reach here, which is why this is AST and not a grep.
|
|
"""
|
|
found: dict[Path, int] = {}
|
|
for root in SEARCH_ROOTS:
|
|
base = REPO / root
|
|
if not base.is_dir():
|
|
continue
|
|
for path in base.rglob("*.py"):
|
|
try:
|
|
tree = ast.parse(path.read_text(encoding="utf-8"))
|
|
except (SyntaxError, UnicodeDecodeError):
|
|
continue
|
|
for node in ast.walk(tree):
|
|
if not isinstance(node, ast.Call):
|
|
continue
|
|
func = node.func
|
|
name = func.attr if isinstance(func, ast.Attribute) else getattr(func, "id", "")
|
|
if name != "HookDecision":
|
|
continue
|
|
for kw in node.keywords:
|
|
if kw.arg == "rollback" and isinstance(kw.value, ast.Constant) and kw.value.value is True:
|
|
found[path] = found.get(path, 0) + 1
|
|
return found
|
|
|
|
|
|
def _declares_flag(module: Path, class_name: str) -> bool:
|
|
tree = ast.parse(module.read_text(encoding="utf-8"))
|
|
for node in ast.walk(tree):
|
|
if not isinstance(node, ast.ClassDef) or node.name != class_name:
|
|
continue
|
|
for stmt in node.body:
|
|
targets = [stmt.target] if isinstance(stmt, ast.AnnAssign) else getattr(stmt, "targets", [])
|
|
if not any(isinstance(t, ast.Name) and t.id == "rolls_back_iterations" for t in targets):
|
|
continue
|
|
value = stmt.value
|
|
if isinstance(value, ast.Constant) and value.value is True:
|
|
return True
|
|
return False
|
|
|
|
|
|
@pytest.fixture(scope="module")
|
|
def producers() -> dict[Path, int]:
|
|
found = _rollback_producers()
|
|
assert found, "no HookDecision(rollback=True) found anywhere -- the AST walk is broken"
|
|
return found
|
|
|
|
|
|
def test_the_walk_sees_the_trees_that_are_known_to_roll_back(producers):
|
|
"""Guards the derivation itself: a walk that silently found nothing, or
|
|
stopped seeing a tree, would let every assertion below pass vacuously."""
|
|
roots = {
|
|
root for path in producers for root in REGISTERED_HOOK if str(path.relative_to(REPO)).startswith(root + "/")
|
|
}
|
|
assert roots == set(REGISTERED_HOOK), (
|
|
"the derived producing trees no longer match the mapped ones; "
|
|
f"derived={sorted(roots)} mapped={sorted(REGISTERED_HOOK)}"
|
|
)
|
|
|
|
|
|
def test_every_rollback_lives_in_a_tree_whose_hook_is_mapped(producers):
|
|
"""The half that catches a *new* engine: an unmapped tree that rolls back has
|
|
no declaration this file can check, which is exactly the state to refuse."""
|
|
unmapped = sorted(
|
|
str(path.relative_to(REPO))
|
|
for path in producers
|
|
if not any(str(path.relative_to(REPO)).startswith(root + "/") for root in REGISTERED_HOOK)
|
|
)
|
|
assert not unmapped, (
|
|
"these files roll back from a tree with no entry in REGISTERED_HOOK, so "
|
|
"nothing checks that the loop is told to hold their drafts: " + repr(unmapped)
|
|
)
|
|
|
|
|
|
@pytest.mark.parametrize("root", sorted(REGISTERED_HOOK))
|
|
def test_a_tree_that_rolls_back_declares_it_on_its_contributed_hook(root):
|
|
rel_module, class_name = REGISTERED_HOOK[root]
|
|
module = REPO / root / rel_module
|
|
assert module.is_file(), f"{root}: {rel_module} is gone -- update REGISTERED_HOOK"
|
|
assert _declares_flag(module, class_name), (
|
|
f"{class_name} ({root}/{rel_module}) can roll back an iteration but does not "
|
|
"declare rolls_back_iterations = True, so the loop streams a draft it may "
|
|
"then retract"
|
|
)
|