## 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).
101 lines
4.3 KiB
Python
101 lines
4.3 KiB
Python
"""The code-flow plugin's wiring: the manifest, the hook factory, admission.
|
|
|
|
The plugin's one seat is the turn-frame hook. This file pins the manifest
|
|
rows, that the registry serves the real factory string, and the D6 admission
|
|
from the rendered config slice: no slice or a disabled slice casts nothing,
|
|
an enabled slice casts the hook, a malformed slice declines with a warning.
|
|
"""
|
|
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
from raven.contracts.loop_hooks import AgentHook
|
|
from raven.contracts.session_events import SessionObserver
|
|
from raven.plugins import DiscoveredPlugin, ManifestOrigin, PluginManifest, PluginRegistry
|
|
from raven.plugins.context import PluginContext, ServiceLocator
|
|
|
|
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, SessionForget, make_flow_hook, make_session_observer # noqa: E402
|
|
|
|
MANIFEST_PATH = PLUGIN_DIR / "raven-plugin.toml"
|
|
|
|
|
|
def ctx_for(tmp_path: Path, config: dict) -> PluginContext:
|
|
return PluginContext(
|
|
config=config,
|
|
services=ServiceLocator(workspace=tmp_path / "home", user_id="u", agent_id="a"),
|
|
)
|
|
|
|
|
|
def test_the_manifest_declares_the_hook_and_the_observer():
|
|
mf = PluginManifest.from_toml_path(MANIFEST_PATH)
|
|
assert mf.id == "code-flow"
|
|
assert [h.name for h in mf.contributes.hooks] == ["code_flow"]
|
|
assert [o.name for o in mf.contributes.session_observers] == ["session_forget"]
|
|
assert mf.contributes.tool_gates == [], "the write gate retired with worktree isolation"
|
|
assert [t.name for t in mf.contributes.tools] == [
|
|
"read_file",
|
|
"write_file",
|
|
"edit_file",
|
|
"list_dir",
|
|
"glob",
|
|
"todo",
|
|
"exec",
|
|
], "the product's own tool face rides this plugin (code_flow/tools/)"
|
|
|
|
|
|
def test_the_registry_builds_the_hook_from_the_real_factory_string(tmp_path):
|
|
"""``location`` is the manifest path, the discovery convention
|
|
(discover.py sets location=manifest_path; activation appends
|
|
location.parent to sys.path) -- so the registry's own importability
|
|
machinery is what serves the factory string here."""
|
|
reg = PluginRegistry()
|
|
mf = PluginManifest.from_toml_path(MANIFEST_PATH)
|
|
reg.activate([DiscoveredPlugin(manifest=mf, source=ManifestOrigin.USER, location=MANIFEST_PATH)])
|
|
assert reg.hook_names() == ["code_flow"]
|
|
assert reg.tool_gate_names() == []
|
|
assert reg.session_observer_names() == ["session_forget"]
|
|
services = ServiceLocator(workspace=tmp_path / "home", user_id="u", agent_id="a")
|
|
observer = reg.build_session_observer("session_forget", config={"enabled": True}, services=services)
|
|
assert isinstance(observer, SessionForget)
|
|
assert isinstance(observer, SessionObserver)
|
|
built = reg.build_hook(
|
|
"code_flow",
|
|
config={"enabled": True},
|
|
services=ServiceLocator(workspace=tmp_path / "home", user_id="u", agent_id="a"),
|
|
)
|
|
assert isinstance(built, CodeFlowHook)
|
|
assert isinstance(built, AgentHook)
|
|
assert built.name == "code_flow"
|
|
|
|
|
|
def test_an_absent_slice_casts_no_surface_at_all(tmp_path):
|
|
"""D6: no config means no hook and no observer."""
|
|
assert make_flow_hook(ctx_for(tmp_path, {})) is None
|
|
assert make_session_observer(ctx_for(tmp_path, {})) is None
|
|
|
|
|
|
def test_a_disabled_slice_casts_no_surface(tmp_path):
|
|
assert make_flow_hook(ctx_for(tmp_path, {"enabled": False})) is None
|
|
assert make_session_observer(ctx_for(tmp_path, {"enabled": False})) is None
|
|
|
|
|
|
def test_an_enabled_slice_casts_the_hook(tmp_path):
|
|
assert isinstance(make_flow_hook(ctx_for(tmp_path, {"enabled": True})), CodeFlowHook)
|
|
|
|
|
|
def test_unknown_slice_keys_are_ignored_not_refused(tmp_path):
|
|
"""The launcher owns the slice spellings; a key this version does not know
|
|
(an older render's ``workspaceGate``, a newer one's knob) must not turn the
|
|
product off."""
|
|
slice_ = {"enabled": True, "workspaceGate": {"allocBase": str(tmp_path)}, "laterKnob": 1}
|
|
assert isinstance(make_flow_hook(ctx_for(tmp_path, slice_)), CodeFlowHook)
|
|
|
|
|
|
def test_a_malformed_slice_declines_the_hook_and_the_observer(tmp_path):
|
|
assert make_flow_hook(ctx_for(tmp_path, {"enabled": "not-a-bool"})) is None
|
|
assert make_session_observer(ctx_for(tmp_path, {"enabled": "not-a-bool"})) is None
|