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

300 lines
13 KiB
Markdown

# 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](#1-three-layers-of-proactivity)
2. [The core idea: periodic Planner plus on-demand spawn](#2-the-core-idea-periodic-planner-plus-on-demand-spawn)
3. [Components](#3-components)
4. [Action space](#4-action-space)
5. [Anti-spam: the NudgePolicy gate](#5-anti-spam-the-nudgepolicy-gate)
6. [Delivery and turn transport: the spine](#6-delivery-and-turn-transport-the-spine)
7. [Scenarios](#7-scenarios)
8. [Cost](#8-cost)
9. [Risks and mitigations](#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.