Raven-1/tests/test_agent_hook_rollback_declarations.py
ypflll dbe259f6d7
refactor(*): close out the participant contract the five plugins now write (#495)
## 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>
2026-09-20 11:36:35 +08:00

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"
)