Raven-1/tests/test_agents_code_flow_sessions.py
0xKT 7a0b5dd311 feat(acp): a prompt is held open while the agent sleeps on an armed wake, and takes a steer
## Summary

An on-call agent submits a job, arms a wake and ends its turn saying so; the wake runs a later turn on the session on its own clock. Over ACP that turn's `end_turn` read as "finished" to the caller: a DAG judging its node spent every continuation on "still watching, wake at 13:13" while the job ran fine (ar-r4, 2026-09-08), and the main agent re-dispatched the work by hand. ACP has no stop reason for "waiting". Replaces the closed !573: **no DAG code changes**, no new node status. The node is `running` because a turn is genuinely in flight.

- **The signal.** The loop-hooks paper gains one key the ACP layer reads for itself: `acp_meta["raven.holdTurn"]` (`{"untilMs", "why"}`). oncall-flow files it at the send fire when the window's campaign is claimed, not concluded, and has one pending wake -- read the same way the owner's answer pulls that wake forward. No campaign, a wake that stood down, or a concluded campaign files nothing and the turn ends as before.
- **The hold** (`raven/acp/methods.py`). A turn that ended `end_turn` with the key filed is not answered. One `tool_call` stands for the wait (its title names the campaign and the next look), with a `tool_call_update` heartbeat every `HOLD_HEARTBEAT_S` (60 s) so a client that clocks liveness by frames sees the agent alive while its model sleeps. The turn slot is reopened with no id to correlate on, so whichever turn ends next on the session -- the wake's, a steer's -- settles it, and the handler decides again from that turn's stash. A wake that arms again keeps the hold; a turn ending with nothing pending answers `end_turn`; a cancel answers `cancelled` as before. The key itself is not passed to the client.
- **Steer.** `_raven/session/steer` is served and advertised under `agentCapabilities._meta` as `raven.steer` (the names raven's own client already uses). Accepted while a prompt is open on the session, held or running: the text is shown on the wire as the person's own line, then sent with `turn.send`'s new `busy: "inject"`. Answers `injected` / `no_turn`.
- **Wire.** `turn.send` gains the optional `busy` param (`const "inject"`): an ordinary send on an idle lane, `BusyPolicy.INJECT` into the running turn otherwise -- the merge a channel's mid-turn message already gets (`gateway_commands.py`). No slot is bound for an injected message; the running turn keeps the lane's. `openrpc.json` and both generated clients moved together.

What raven's client side already does, unchanged: the DAG stall watcher resets on any frame (the heartbeat keeps it quiet, and a stopped heartbeat raises the existing stall notice after ten minutes); a sub-agent process that dies fails the request and the node takes its ordinary path; the pool's `_responsive` treats a prompt in flight as busy.

## Review round 1 (2026-09-09, on !600, superseded by this MR)

- **`busy: inject` reads the scheduler's lane state too.** `is_turn_active` knows only the turns `turn.send` started; an armed wake is submitted to the scheduler directly (`make_on_session_wake`) and never binds that map, so a steer during a running wake queued a second turn and answered `injected`. `turn.send` now asks `Scheduler.has_inflight(lane)` as well, and merges (`BusyPolicy.INJECT`) when either record says the lane is running. Pinned: `test_busy_inject_merges_into_a_wake_the_real_scheduler_is_running` -- the reviewer's reproduction on the real `Scheduler`, a turn submitted the way `make_on_session_wake` submits one; with the lane check bypassed it reads `pending=1, inject_mailbox=0`, with it `(1, 0)` in the mailbox and the running turn drains the text.
- Branch renamed to snake_case and both commits carry the `Co-authored-by: Claude (<model-id>)` trailer, per AGENTS.md §2–3; that is why this MR replaces !600 rather than continuing it.

## Review round 2 (2026-09-10)

- **A wake re-armed during its own run survives the writeback.** `CronService._writeback_locked` reloaded the store after the run and, for a one-shot with `delete_after_run`, overwrote the id with the finished run's state and removed it -- but the turn the wake ran had just called `schedule_wake` under the same key, so the id now named the *next* look. It vanished, and the held prompt had nothing left to settle it. A stored job under the fired id whose `at` schedule the run never had is treated as the new wake it is: claim cleared, run recorded, schedule kept, not deleted. Pinned on the real service: `test_a_wake_re_armed_during_its_own_run_survives_the_writeback` (reads `[]` without the fix, the reviewer's state) and the unchanged one-shot deletion beside it. Cron, proactive, sentinel and on-call suites: 968 passed.

## Review round 3 (2026-09-10)

- **An undrained inject stays visible and cancellable.** `busy: inject` dropped the scheduler's handle; when the host turn ended past its last drain, the spine's fallback ran the text as a turn nothing owned -- `turn.cancel` a no-op, no `message.start`. The handle is now kept per lane under an id minted for the text; `turn.cancel` / `session.interrupt` reach it when the active slot is empty (mailbox, queued fallback, or running); and when the fallback turn starts, the RPC sink (`on_turn_start`, wired from bootstrap) binds the lane to it and opens it on the wire with the person's words. `turn.send` answers the inject's own id. Pinned through `build_rpc_spine` with the reviewer's shape (a loop that drains once, an inject after it): `test_an_undrained_inject_runs_as_a_turn_the_surface_can_see_and_cancel` and `test_a_pending_inject_can_be_cancelled_before_it_merges_or_falls_back`; both read the reviewer's state (`turn_ids` empty, cancel finding nothing) with the fix bypassed.
- **Line ceiling.** The contract comment is five lines; `raven/contracts` is 2,519 against 2,520, one line of headroom on the current `main` (2,514).
- Non-blocking items taken: `SchedulerDrainingError` on the inject path exits as `turn_failed`; the title is announced before the hold; the steer constants sit below the cancel constant's docstring; three edges pinned (a held prompt settled by a wake turn's uncorrelated ending through `send_frame`, the hold key never in the client's `_meta`, `raven.toolName` on the wait row).
- Focused suite (reviewer's list plus the touched files): 948 passed on Python 3.12.

## Review round 4 (2026-09-10)

- **Every pending inject is kept, per lane and per id.** One replaceable record per lane kept only the newest steer; two steers after the host's last drain fall back in turn, and the first started unowned while a cancel took out the second. The record is now `lane -> {inject id: (handle, text)}` in arrival order: each fallback promotes its own handle, and a cancel with no active turn reaches the oldest pending one -- the one the spine runs next. Pinned: `test_two_undrained_injects_each_get_their_own_turn_promoted_and_cancelled` (both promoted with their own ids and `message.start`, cancelled one after the other; runner saw all three turns). Focused suite: 949 passed.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

```
uv run pytest tests/test_acp_methods.py tests/test_acp_protocol.py tests/test_rpc_turn_send.py \
  tests/test_rpc_schema_match.py tests/test_acp_updates.py tests/test_acp_server.py -q      # 766 passed
uv run pytest tests/test_agents_oncall_flow_hooks.py tests/test_agents_oncall_flow_actions.py \
  tests/test_agents_oncall_flow_budget.py tests/test_agents_oncall_flow_readings.py \
  tests/test_agents_oncall_flow_escalation_tools.py -q                                       # 99 passed
uv run ruff check raven tests agents && uv run ruff format --check raven tests agents        # clean
uv run lint-imports                                                                          # 9 kept, 0 broken
cd ui-tui && npm run lint:rpc && npx tsc --noEmit; cd ui-web && npm run gen:check && npx tsc --noEmit   # in sync, clean
```

New tests: `TestHeldTurn` (held across an armed wake, held again on a re-arm, heartbeat on the wait call, cancel while held, a non-`end_turn` stop is not held; every frame validated against the ACP schema), `TestSteer` (advertised, `no_turn` when idle, a held prompt takes the words as a turn with `busy: inject`, refusals), `busy: inject` on a busy and an idle lane in `test_rpc_turn_send.py`, and the plugin's hold stamping through the real `CronService` grant (filed with a pending wake; not filed without one, after the wake stands down, or once the campaign concluded).

Not done: no end-to-end run of a real on-call wake through a held prompt yet -- unit tests only.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (the hold is invisible to a person except as a "waiting for ..." tool row)

## Risk

- [x] Backward compatibility considered: a turn that files no `raven.holdTurn` is answered exactly as before; `busy` is optional and absent from every existing caller; the steer method and capability are additive.
- [x] Rollback path is clear: revert the two commits.

A held prompt holds one `max_concurrent_subagents` slot (default 8) for the wait's duration on the caller's side; raised in config if it bites.

## Related

Replaces !573 (closed). Follows !518 (stall notice) and !520 (unprompted-turn route; a wake that runs under a held prompt no longer takes it for DAG nodes).
2026-09-11 02:37:55 +00:00

246 lines
9.7 KiB
Python

"""The code flow's session ledger and the concurrency notice it drives.
Parallel raven-code DAG nodes are sessions of ONE raven-code process on ONE
working directory (the host's connection pool keeps one process per agent
name and mints each node its own session). Nothing locks that directory any
more, so a session is told -- at the start of its turn, in its own prompt --
how many other sessions are working beside it, and only then: a lone session
gets no notice.
"""
import subprocess
import sys
from pathlib import Path
import pytest
from raven.agent import workdir
from raven.contracts.loop_hooks import AgentHookContext, HookDecision
REPO = Path(__file__).resolve().parent.parent
PLUGIN_DIR = REPO / "agents" / "raven-code" / "plugins" / "code-flow"
sys.path.insert(0, str(PLUGIN_DIR))
from code_flow.flow import CodeFlowHook, make_session_forget # noqa: E402
from code_flow.sessions import SessionLedger # noqa: E402
class _Clock:
def __init__(self) -> None:
self.now = 1000.0
def __call__(self) -> float:
return self.now
def make_repo(path: Path) -> str:
path.mkdir(parents=True, exist_ok=True)
subprocess.run(["git", "init", "-q", str(path)], check=True)
subprocess.run(["git", "-C", str(path), "config", "user.email", "t@t"], check=True)
subprocess.run(["git", "-C", str(path), "config", "user.name", "t"], check=True)
(path / "a.py").write_text("x = 1\n")
subprocess.run(["git", "-C", str(path), "add", "-A"], check=True)
subprocess.run(["git", "-C", str(path), "commit", "-qm", "init"], check=True)
return subprocess.run(
["git", "-C", str(path), "rev-parse", "HEAD"], check=True, capture_output=True, text=True
).stdout.strip()
async def _system(hook: CodeFlowHook, key: str, cwd: Path, text: str = "do the task") -> str:
ctx = AgentHookContext(
session_key=key,
messages=[{"role": "system", "content": ""}, {"role": "user", "content": text}],
context_window_tokens=8192,
)
with workdir.bind(cwd):
inbound = AgentHookContext(session_key=key, inbound_content=text)
assert (await hook.before_user_inbound(inbound)).modified_content is None
assert inbound.inbound_content == text
decision = await hook.before_iteration(ctx)
assert decision.short_circuit_result is None
return ctx.messages[0]["content"]
async def _sent(hook: CodeFlowHook, key: str, cwd: Path) -> HookDecision:
with workdir.bind(cwd):
return await hook.after_send(AgentHookContext(session_key=key, outbound_content="done", metadata={}))
@pytest.mark.asyncio
async def test_a_lone_session_gets_no_notice(tmp_path):
hook = CodeFlowHook(ledger=SessionLedger(clock=_Clock()))
text = await _system(hook, "s1", tmp_path)
assert text == ""
@pytest.mark.asyncio
async def test_a_second_session_on_the_same_directory_is_told_about_the_first(tmp_path):
hook = CodeFlowHook(ledger=SessionLedger(clock=_Clock()))
await _system(hook, "s1", tmp_path)
text = await _system(hook, "s2", tmp_path, "fix the parser")
assert text != ""
assert text.startswith("# Workspace concurrency")
assert "1 other Raven-Code session" in text
assert "fix the parser" not in text, "the task stays in the user message"
@pytest.mark.asyncio
async def test_the_notice_counts_every_other_session_in_flight(tmp_path):
hook = CodeFlowHook(ledger=SessionLedger(clock=_Clock()))
await _system(hook, "s1", tmp_path)
await _system(hook, "s2", tmp_path)
text = await _system(hook, "s3", tmp_path)
assert "2 other Raven-Code sessions" in text
@pytest.mark.asyncio
async def test_sessions_on_different_directories_do_not_hear_about_each_other(tmp_path):
hook = CodeFlowHook(ledger=SessionLedger(clock=_Clock()))
await _system(hook, "s1", tmp_path / "one")
text = await _system(hook, "s2", tmp_path / "two")
assert text == ""
@pytest.mark.asyncio
async def test_a_session_that_finished_its_turn_no_longer_counts(tmp_path):
hook = CodeFlowHook(ledger=SessionLedger(clock=_Clock()))
await _system(hook, "s1", tmp_path)
await _sent(hook, "s1", tmp_path)
text = await _system(hook, "s2", tmp_path)
assert text == ""
@pytest.mark.asyncio
async def test_a_session_that_never_reported_back_expires_after_the_ttl(tmp_path):
"""A failed or cancelled turn fires no after_send, so its in-flight mark
would otherwise stick forever and every later session would be warned
about a ghost."""
clock = _Clock()
hook = CodeFlowHook(ledger=SessionLedger(clock=clock, ttl_s=60.0))
await _system(hook, "s1", tmp_path)
clock.now += 61.0
text = await _system(hook, "s2", tmp_path)
assert text == ""
@pytest.mark.asyncio
async def test_a_deleted_session_is_forgotten(tmp_path):
ledger = SessionLedger(clock=_Clock())
hook = CodeFlowHook(ledger=ledger)
await _system(hook, "s1", tmp_path)
make_session_forget(ledger).on_session_deleted("s1", True)
text = await _system(hook, "s2", tmp_path)
assert text == ""
assert ledger.record("s1") is None
@pytest.mark.asyncio
async def test_the_notice_does_not_need_a_git_repository(tmp_path):
"""Nothing here reads git to decide: two sessions in a plain directory
are as concurrent as two in a checkout."""
hook = CodeFlowHook(ledger=SessionLedger(clock=_Clock()))
await _system(hook, "s1", tmp_path)
text = await _system(hook, "s2", tmp_path)
assert text != ""
@pytest.mark.asyncio
async def test_the_ledger_pins_a_sessions_base_commit_at_its_first_turn(tmp_path):
"""The base a later workspace report measures against: HEAD when the
session first spoke, kept across its turns, None outside git."""
repo = tmp_path / "repo"
head = make_repo(repo)
ledger = SessionLedger(clock=_Clock())
hook = CodeFlowHook(ledger=ledger)
await _system(hook, "s1", repo)
assert ledger.record("s1").base_commit == head
(repo / "b.py").write_text("y = 2\n")
subprocess.run(["git", "-C", str(repo), "add", "-A"], check=True)
subprocess.run(["git", "-C", str(repo), "commit", "-qm", "more"], check=True)
await _sent(hook, "s1", repo)
await _system(hook, "s1", repo)
assert ledger.record("s1").base_commit == head, "the base does not move with the session's own commits"
await _system(hook, "plain", tmp_path / "plain")
assert ledger.record("plain").base_commit is None
# --------------------------------------------------------------------------- #
# who shared a directory, and a long turn that keeps iterating #
# --------------------------------------------------------------------------- #
@pytest.mark.asyncio
async def test_sessions_that_coexist_on_a_directory_name_each_other_as_peers_for_life(tmp_path):
ledger = SessionLedger(clock=_Clock())
hook = CodeFlowHook(ledger=ledger)
await _system(hook, "s1", tmp_path)
assert ledger.record("s1").shared is False
await _system(hook, "s2", tmp_path)
assert ledger.record("s1").peers == {"s2"} and ledger.record("s2").peers == {"s1"}
await _sent(hook, "s1", tmp_path)
await _sent(hook, "s2", tmp_path)
assert ledger.record("s1").shared and ledger.record("s2").shared, "finishing a turn does not unshare a tree"
@pytest.mark.asyncio
async def test_sessions_on_different_directories_are_not_peers(tmp_path):
ledger = SessionLedger(clock=_Clock())
hook = CodeFlowHook(ledger=ledger)
await _system(hook, "s1", tmp_path / "a")
await _system(hook, "s2", tmp_path / "b")
assert ledger.record("s1").shared is False and ledger.record("s2").shared is False
@pytest.mark.asyncio
async def test_a_session_arriving_after_its_predecessor_was_deleted_is_not_shared(tmp_path):
"""A deleted session left the ledger, and its commits sit before the
newcomer's base anyway, so the newcomer's report stays its own."""
ledger = SessionLedger(clock=_Clock())
hook = CodeFlowHook(ledger=ledger)
await _system(hook, "s1", tmp_path)
await _sent(hook, "s1", tmp_path)
make_session_forget(ledger).on_session_deleted("s1", True)
await _system(hook, "s2", tmp_path)
assert ledger.record("s2").shared is False
@pytest.mark.asyncio
async def test_a_predecessor_still_on_the_ledger_counts_as_having_shared(tmp_path):
"""Records outlive turns: a session that finished a turn but was not
deleted may speak again, so the newcomer is shared with it."""
ledger = SessionLedger(clock=_Clock())
hook = CodeFlowHook(ledger=ledger)
await _system(hook, "s1", tmp_path)
await _sent(hook, "s1", tmp_path)
await _system(hook, "s2", tmp_path)
assert ledger.record("s2").peers == {"s1"}
@pytest.mark.asyncio
async def test_a_long_turn_that_keeps_iterating_stays_counted_past_the_ttl(tmp_path):
"""The ttl is for a turn that stopped reporting. One that is still
iterating refreshes its mark at every iteration, so a session working for
longer than the ttl is still announced to a newcomer."""
clock = _Clock()
hook = CodeFlowHook(ledger=SessionLedger(clock=clock, ttl_s=60.0))
await _system(hook, "s1", tmp_path)
clock.now += 50.0
await hook.before_iteration(AgentHookContext(session_key="s1"))
clock.now += 50.0
text = await _system(hook, "s2", tmp_path)
assert text != "", "100s after its start the still-iterating s1 was forgotten"
@pytest.mark.asyncio
async def test_an_iteration_of_an_unknown_or_finished_session_refreshes_nothing(tmp_path):
clock = _Clock()
ledger = SessionLedger(clock=clock, ttl_s=60.0)
hook = CodeFlowHook(ledger=ledger)
await hook.before_iteration(AgentHookContext(session_key="ghost"))
assert ledger.record("ghost") is None
await _system(hook, "s1", tmp_path)
await _sent(hook, "s1", tmp_path)
clock.now += 10.0
await hook.before_iteration(AgentHookContext(session_key="s1"))
assert ledger.record("s1").in_flight is False