Raven-1/docs/Proactivity-Plan.md
userName20260323 e708f34a91
docs: align bilingual documentation with runtime behavior (#551)
## 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>
2026-09-20 19:20:27 +08:00

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

  1. Three layers of proactivity
  2. The core idea: periodic Planner plus on-demand spawn
  3. Components
  4. Action space
  5. Anti-spam: the NudgePolicy gate
  6. Delivery and turn transport: the spine
  7. Scenarios
  8. Cost
  9. 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:

  1. Three-way decisions, not binary: stay silent, send a short message, or run a multi-step task — not just notify-or-not.
  2. A per-user model: proactivity preferences must vary by user, not be a single global setting.
  3. A feedback loop: every nudge collects a signal that tightens or loosens future behavior.
  4. Low intrusion first: conservative defaults, gradual takeover; the quality of the first few proactive messages decides whether the user keeps the feature.
  5. 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 TurnRequest to the per-process Scheduler (raven/spine/scheduler.py), which routes it to a per-conversation serial Lane. Each request carries an Origin — USER, SENTINEL, CRON, HEARTBEAT, or SUBAGENT — 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-loop backend'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.