## Summary - Align English and Chinese documentation for Docker/Compose, sandbox execution, and the in-tree tracing API with verified runtime behavior. - Separate proactivity usage guidance from developer design and implementation details, with configuration, troubleshooting, cost, and safety boundaries. - Update navigation and remove redundant section separators. Keep page URLs unchanged. - Preserve published proactivity section and title anchors in both languages. Use native aliases for same-page content and visible migration links for moved sections, with regression tests. - Clarify Sentinel delivery fallback and menu-selection requirements, tracing-on/off argument handling, headless CLI menu output, and viewer descriptor lookup. Add focused regression coverage without changing runtime behavior. - Clarify the initial frozen baseline and improve Evolver wording in the bilingual site and repository mapping. Keep its structure, navigation, implementation terms, and technical claims unchanged; broader Evolver documentation work is excluded. - No runtime changes. ## Type - [ ] Fix - [ ] Feature - [x] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification Passed on the rebased revision: ```bash uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x # 395 passed uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site # Strict English and Chinese builds passed UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py' UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs git diff --check origin/main...HEAD # All passed ``` - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed Documentation checks also covered bilingual examples and the proactivity JSON configuration schema. A built-HTML audit verified all 110 historical proactivity section fragments and four title fragments, including same-language migration destinations, and found zero broken internal fragment links across 29 HTML pages (672 links). Replaying pre-fix content made all four page compatibility cases fail as expected. The new descriptor-directory test failed on all three documents before their stale paths were corrected. Added coverage exercises tracing on/off, bare-number versus explicit menu selection with incomplete classifier configuration, and discovery-menu dispatch through the real CLI stack's headless sink. Runtime type checks and the full repository test suite were not run; no runtime code changes. No browser click test, live LLM, real-VM, or container end-to-end run was performed. ## Risk Documentation-only, with regression tests. Proactivity navigation changes, but page URLs and historical heading fragments are preserved. An old link to content moved between pages lands on a visible migration entry and requires one click to reach the new section; no JavaScript redirect is needed. Existing queued-nudge policy and external-agent isolation limitations are described, not fixed. Roll back by reverting the documentation and associated test changes; no data migration is involved. - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes ## Related Issues N/A --------- Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com> Co-authored-by: Codex <noreply@openai.com>
13 KiB
Raven Proactivity — Design
From passive notification to anticipatory collaboration: the design of Raven's proactivity subsystem.
This document describes the design intent — what the proactivity subsystem is
meant to be and why it is shaped the way it is. Its companion,
docs/Proactivity-Implementation.md, is the as-built reference: it maps each
piece to a module path under raven/proactive_engine/ and the spine
(raven/spine/).
Contents
- Three layers of proactivity
- The core idea: periodic Planner plus on-demand spawn
- Components
- Action space
- Anti-spam: the NudgePolicy gate
- Delivery and turn transport: the spine
- Scenarios
- Cost
- Risks and mitigations
1. Three layers of proactivity
A widely used framing splits agent proactivity into three layers, each built on the one before it:
| Layer | Name | Definition |
|---|---|---|
| L1 | Reactive monitoring | An event has happened, is detected, and the agent decides whether to notify the user. |
| L2 | Predictive / routine-based | Recurring patterns are learned from the user's history and acted on before the user asks. |
| L3 | Anticipatory / contextual | The agent reasons over the user's current situation, infers a latent need, and acts. |
A system that stops at L1 is felt as a notifier, not a collaborator. Raven's subsystem reaches L2 and L3 while staying conservative by default.
Design principles that follow from this:
- Three-way decisions, not binary: stay silent, send a short message, or run a multi-step task — not just notify-or-not.
- A per-user model: proactivity preferences must vary by user, not be a single global setting.
- A feedback loop: every nudge collects a signal that tightens or loosens future behavior.
- Low intrusion first: conservative defaults, gradual takeover; the quality of the first few proactive messages decides whether the user keeps the feature.
- Content quality over frequency: one precise proactive message beats ten generic notifications.
2. The core idea: periodic Planner plus on-demand spawn
The subsystem does not run a second agent loop and does not subscribe to an
event stream. Instead it wakes periodically, reads a packaged context, and makes
one structured LLM decision per tick. When a decision needs multi-step
execution, it spawns a micro-agent through the existing SubagentManager rather
than reimplementing a loop.
This keeps the cost bounded (one LLM call per tick, a tail-bounded spawn) while
still covering routine automation (L2) and multi-step anticipation (L3). The
periodic Planner mirrors the shape of the heartbeat service
(raven/proactive_engine/schedulers/heartbeat/service.py), and execution
reuses the subagent machinery rather than a bespoke runtime.
The two sources of proactivity are:
- Sentinel — the LLM decides each tick whether and how to reach the user.
- Cron — the user explicitly schedules a reminder.
Both reach the agent as origin-tagged turns through the spine, and both pass the
same NudgePolicy ledger so the two surfaces never double-remind the user on
the same topic.
3. Components
ProactivePlanner — periodic reasoner
Wakes on its own interval, reads a single packaged context, and makes one LLM
call that returns a structured decision without executing the chosen action.
Reported LLM errors, missing tool calls, and non-dict tool arguments become
skip. Exceptions propagate to the runner, which first tries a guarded
high-priority deadline fallback and otherwise returns skip.
Its only input is the assembled PlannerContext: the user's long-term memory, a
tail of recent history, currently active sessions, learned routines, calendar
entries, the current NudgePolicy state, the previous tick's decision, a recent
fire history, selected sections of an attention.md state file, and a folded
window of recent behavior. The Planner sees nothing else.
ContextAssembler — input packaging
Aggregates every signal source into the PlannerContext, with graceful
degradation per field (a missing source yields an empty value rather than a
crash). This is the single place that decides what the Planner gets to see.
RoutineLearner — behavior-pattern learning
Mines recurring patterns from the user's history (recency-weighted token frequency, no LLM required) and emits candidate routines for the Planner to consume. Candidates are persisted with a confirmation lifecycle: a pattern is proposed before it is acted on, confirmed by the user, then triggered automatically; it is paused on rejection and retired after long disuse.
NudgePolicy — the shared anti-spam gate
Every proactive message — from any executor and from the task-discovery menu —
must pass NudgePolicy.check() before it is delivered. It enforces quotas,
quiet hours, cooldowns, content de-duplication, and per-topic limits, and it
learns to tighten or loosen from user feedback. See section 5.
ProactiveSpawn — multi-step execution bridge
When a decision is spawn_agent, this wraps SubagentManager.spawn(...) to run
a micro-agent for a multi-step task (for example a status check or a digest).
It checks the shared NudgePolicy before dispatch and records the dispatch in
that same quota ledger. SubagentManager returns the result through a
SUBAGENT-origin turn in the originating session. The wrapper adds no new
agent loop, private quota, or end-to-end task timeout; concurrency and dispatch
rate limits come from SubagentManager.
Task discovery — anticipatory menus
A daily batch reads recent memory and history, proposes a small menu of candidate tasks, and posts it for the user to pick from by number. A pick is caught before it reaches the agent and routed to an executor (reply, tool, or spawn), optionally behind a confirm step.
4. Action space
A Planner tick returns exactly one of five actions, validated against a tool schema so the Planner cannot emit a malformed decision:
skip— nothing worth doing this tick.nudge— send a standalone message now.nudge_inject— append the message to the agent's next reply in the target session (the user is already in that conversation, so the information extends the current thread naturally).nudge_defer— wait until the target session's current thread settles, then send (the user is busy with something else and should not be interrupted).spawn_agent— dispatch a micro-agent for a multi-step task.
nudge_inject and nudge_defer are the distinctive ones: they make the agent
aware of what the user is doing right now, rather than only choosing send-now or
not. Their execution paths are described in the implementation reference.
5. Anti-spam: the NudgePolicy gate
The NudgePolicy is a layered gate with a clean read/write split: check() is a
pure verdict, and record_fired() writes state only after a successful
delivery. The layers, applied in order, cover:
- quiet hours (a static window plus a per-hour window learned from feedback);
- per-persona do-not-disturb windows;
- per-day and per-hour quotas;
- per-session and per-dismissal cooldowns;
- per-topic acceptance-rate and hard-reject cooldowns;
- content de-duplication within a window;
- a rolling per-topic quota stack (hour / day / week).
A high-priority message can bypass some soft layers, but the hard quotas and cooldowns hold, and the high-priority bypass is itself withdrawn when the user has shown low acceptance even of high-priority messages.
The hour quota is scaled by an adaptive multiplier that moves symmetrically with the user's recent acceptance rate: a highly engaged user can receive more, a disengaged user fewer. The multiplier is also surfaced to the Planner prompt as a soft signal so the Planner can raise its own value threshold and avoid LLM calls that would only be denied.
The policy is personalizable: a ProactivityPreferencesReader lets learned user
preferences override the static config, but only in the tightening direction (a
user preference can widen the quiet window, never narrow it).
All of this state is persisted across processes (an fcntl-locked atomic-rename
JSON store), so the REPL and the gateway share one ledger and a restart does not
lose quota or cooldown state.
6. Delivery and turn transport: the spine
There is no message bus. The spine is the sole turn transport and delivery path.
- A turn is submitted as a
TurnRequestto the per-processScheduler(raven/spine/scheduler.py), which routes it to a per-conversation serialLane. Each request carries anOrigin—USER,SENTINEL,CRON,HEARTBEAT, orSUBAGENT— that drives concurrency pooling and control eligibility (raven/spine/turn.py). - A reply, or any proactive message, is delivered through the
DeliveryHub(raven/spine/delivery.py), which routes each deliverable to its channel's outlet. A plain nudge is posted to the hub directly (not run back through a turn), so the user receives it as a standalone message and the agent cannot "act on" a reminder. - Sentinel, cron, and heartbeat all reach the agent the same way: as
origin-tagged turns submitted through the spine. Cron's reminder fires as a
CRON-origin turn; the heartbeat wakes as its own service.
USER-origin turns get the full user-inbound treatment (engagement detection,
the response-modifier chain that lets nudge_inject piggyback). Proactive
system turns that should not be treated as user input, or should not have a
nudge layered onto their own output, are gated out of those hooks by origin.
7. Scenarios
L2 — routine automation
The user has checked the weather on the last few Monday mornings. The
RoutineLearner surfaces a candidate routine; on the next Monday-morning tick the
Planner proposes it ("I noticed you check the weather on Monday mornings — want
me to do it automatically?"). Once confirmed, a later Monday-morning tick emits
spawn_agent to fetch and summarize the forecast and delivers a concise digest.
L3 — memory-linked reminder
The user mentioned an SSL certificate expiring at the end of the month. Reading
memory, the Planner reminds the user a week out (nudge, medium priority) and,
if no action followed, again two days out at high priority.
L3 — context-aware resumption
The user was debugging a Redis connection two hours ago and never replied. The
Planner reads the active session, sees what the agent last suggested, and asks a
contextual follow-up ("Did the Redis connection issue get sorted? If
systemctl start redis did not help, I can check firewall rules or the bind
address.") — not a context-free "are you still there?".
L3 — proactive status check
The user deployed to staging and said "let it run for a bit". After a reasonable
interval the Planner emits spawn_agent to run a health check and reports the
result — the agent has already looked, rather than reminding the user to look.
8. Cost
When fast paths do not handle a tick, the Planner makes a bounded LLM call
(a small input, a small structured output). The default tick interval is
30 minutes, and the RoutineLearner uses no LLM. Spawned micro-agents add
multi-step costs, subject to the selected backend's limits and SubagentManager's
shared concurrency and dispatch-rate limits. ProactiveSpawn adds no overall
task timeout; individual model or tool timeouts are not a task-wide deadline.
The whole subsystem is off by default
(sentinel.enabled=false), so an opt-out user pays nothing.
Tail-risk controls:
- SubagentManager's shared concurrency and per-session dispatch-rate limits;
- the built-in
raven-loopbackend's iteration cap; - model and tool timeouts where configured by the selected backend;
- the shared NudgePolicy rate limit, charged when a spawn is dispatched.
9. Risks and mitigations
Over-notification
If the Planner misjudges and pushes low-value nudges, the user disables the
feature. Mitigations: conservative defaults; the RoutineLearner proposes before
it acts; the adaptive NudgePolicy tightens on low acceptance; the Planner prompt
defaults to skip.
Planner decision quality
A small model can misjudge complex context. Mitigations: the Planner output is a structured tool call (reliable to parse); the context is kept small to stay in the model's sweet spot; high-impact actions require at least medium priority; the Planner model is configurable for users who want a stronger one.
Spawn safety
An unattended micro-agent could take a damaging action. Sentinel is off by
default, but enabling it also wires the spawn path. The built-in raven-loop
backend omits messaging and recursive-spawn tools and has an iteration cap.
Workspace restriction depends on tools.restrict_to_workspace (default
false) and any per-agent override; ProactiveSpawn does not force it on.
It also adds no overall task timeout. External ACP and CLI agents run as host
processes and need their own isolation and execution limits.
History format drift
The RoutineLearner depends on a timestamped history format. Mitigations: the history is written by the consolidator under a controlled format, the parser tolerates deviation, and an unparseable entry is skipped rather than fatal.