feat(kernel): proactive v2 — event-driven proactive architecture

[crrow]

Description

Implement event-driven proactive architecture (Proactive V2) to replace the polling-only heartbeat mechanism. Three layers: Event Source (ProactiveSignal variants in KernelEvent), Event Filter (rule-based quiet hours/cooldowns/rate limiting), and Mita Context Pack (structured event delivery replacing vague heartbeat message).

Phase 1 scope: internal session events (SessionIdle, TaskFailed, SessionCompleted) + time events (MorningGreeting, DailySummary) + filter + context pack.

Design doc: docs/plans/2026-03-20-proactive-v2-design.md

Component

kernel (core runtime, heartbeat, event bus)

Alternatives considered

• Separate event system outside KernelEvent — rejected to avoid dual event pipelines
• LLM-based filtering — rejected for cost; pure rules suffice
• Heartbeat as sole driver — current state, insufficient for real-time response

[crrow]

Context Investigation

Existing Architecture

Current proactive system (kernel/src/proactive.rs): Only handles group-chat judgment (should Mita reply to a non-mentioned message). Not related to the event-driven proactive system we're building.

KernelEvent (kernel/src/event.rs): Unified event enum with priority tiers (Critical/Normal/Low). Already has MitaHeartbeat and IdleCheck variants. New ProactiveSignal variant fits naturally.

Processor 0 scheduler (kernel/src/kernel.rs:427-544): Only P0 computes min(next_mita_heartbeat, next_job_deadline) via tokio::select!. Adding next_proactive_time_event to this calculation is straightforward — no new threads or processors needed.

IdleCheck handler (line 683-687): Currently only reaps terminal processes after 300s. Perfect emit point for SessionIdle signal — we can add signal emission alongside the reap.

handle_scheduled_task error path (line 1442-1447): Logs error only, no notification. Good emit point for TaskFailed signal.

Config: AppConfig loaded from YAML. MitaConfig has heartbeat_interval. Proactive config can live at config_dir()/mita/proactive.yaml as a separate file, loaded independently.

Mita tools: dispatch_rara, notify, read_tape, list_sessions, update_soul_state — all existing tools remain unchanged. New mita_update_proactive_config tool follows same pattern.

Prior Work

• No previous proactive v2 attempts found
• feat(kernel): TaskReport entry + NotificationBus for background task result awareness #435 (TaskReport + NotificationBus) is related but orthogonal — handles task result notifications, not proactive event signals
• Current proactive.rs (group chat judgment) stays unchanged — different concern

AGENT.md Invariants (kernel)

• Tape is append-only source of truth — context pack must read from tape, not cache
• StreamDelta ordering in openai.rs — unaffected
• GroupPolicy default must remain MentionOrSmallGroup — unaffected

[crrow]

Design Analysis

Approaches Considered

A) Separate event system — New EventBus alongside KernelEvent for proactive signals.

• Pro: Clean separation
• Con: Dual event pipelines, extra complexity, violates kernel's unified event model

B) KernelEvent extension (selected) — Add ProactiveSignal as a new KernelEvent variant, filter inline in handle_event.

• Pro: Reuses existing event queue, priority system, processor architecture. Zero new infrastructure.
• Con: Slightly enlarges KernelEvent enum
• Why selected: Minimal surface area, follows existing patterns, no architectural changes

C) Pure Mita tool-based — Mita periodically polls for signals via tools.

• Pro: No kernel changes
• Con: Still polling-based, high LLM cost, no real-time response

Selected Approach: B — KernelEvent Extension

Key Decisions

1. ProactiveSignal as KernelEvent variant — not a separate event system. Follows existing pattern where MitaHeartbeat, ScheduledTask are already KernelEvent variants.

2. ProactiveFilter is pure rule-based — zero LLM cost. Quiet hours, cooldowns, rate limiting. Runs in handle_event before forwarding to Mita.

3. Context pack replaces vague heartbeat message — structured message with event kind, session context, Mita history, available actions. Heartbeat also uses this format.

4. proactive.rs → proactive/ module directory — existing proactive.rs (group chat judgment) moves to proactive/judgment.rs, new files added alongside.

5. Time events via Processor 0 scheduler — extend existing min(next_mita, next_job) to include next_proactive_time_event. No new threads.

6. Config at config_dir()/mita/proactive.yaml — separate from main config.yaml, hot-updatable by Mita via new tool.

Implementation Steps

1. Add ProactiveSignal enum + ProactiveFilter — new kernel/src/proactive/signal.rs and filter.rs
2. Add proactive config — kernel/src/proactive/config.rs, load from YAML
3. Restructure proactive module — move proactive.rs → proactive/mod.rs + proactive/judgment.rs
4. Add KernelEvent::ProactiveSignal variant — extend event.rs
5. Build context pack — kernel/src/proactive/context.rs, structured message builder
6. Wire signal emit points — IdleCheck, handle_scheduled_task error path, TurnCompleted
7. Extend Processor 0 scheduler — add time event triggers (morning/daily)
8. Handle ProactiveSignal in handle_event — filter → context pack → deliver to Mita
9. Add mita_update_proactive_config tool — app/src/tools/
10. Reformat heartbeat as context pack — update handle_mita_heartbeat

[crrow]

Plan Review — Round 1

Review Findings (4 issues)

#	Issue	Resolution
1	Separate config file diverges from single-YAML convention	Accept. Nest ProactiveConfig under mita.proactive in main config.yaml. No separate file.
2	Heartbeat reformat may break Mita format expectations	Low risk. Mita receives heartbeat as synthetic user message text — no structured parsing. Will update format and Mita system prompt fragment together.
3	"Sensible defaults" contradicts no-defaults-in-Rust rule	Accept. If mita.proactive section is absent, proactive is disabled with info log. No Rust-side defaults.
4	Hot-update tool should be deferred	Accept. Cut step 9 (mita_update_proactive_config). Ship core pipeline first.

Revised Implementation Steps

1. Restructure proactive.rs → proactive/ module (judgment.rs + mod.rs)
2. Add ProactiveSignal enum in proactive/signal.rs
3. Add ProactiveFilter in proactive/filter.rs
4. Add ProactiveConfig under MitaConfig in config, loaded from mita.proactive YAML section
5. Add KernelEvent::ProactiveSignal variant to event.rs
6. Build context pack in proactive/context.rs
7. Wire signal emit points (IdleCheck → SessionIdle, scheduled task error → TaskFailed, TurnCompleted → SessionCompleted)
8. Extend Processor 0 scheduler for time events (MorningGreeting, DailySummary)
9. Handle ProactiveSignal in handle_event (filter → context pack → deliver to Mita)
10. Reformat heartbeat as structured context pack

Removed: mita_update_proactive_config tool (deferred to follow-up)

[crrow]

Implementation started. Scale: medium (single worktree). Branch: issue-786-proactive-v2

[crrow]

PR #793 created — all CI checks green.

Implemented:

• Steps 1-6: Proactive module restructure, ProactiveSignal enum, ProactiveConfig, ProactiveFilter, KernelEvent variant, context pack builder
• Step 7: Signal emit points (IdleCheck → SessionIdle, TaskFailed on spawn error, SessionCompleted on worker finish)
• Step 8: Processor 0 scheduler for MorningGreeting/DailySummary time events
• Step 9: handle_proactive_signal + deliver_proactive_to_mita
• Step 10: Heartbeat reformatted as structured context pack
• Step 11: ProactiveConfig wired through MitaConfig → KernelConfig
• AGENT.md updated with proactive V2 section

Not included (per spec): mita_update_proactive_config tool (deferred).

[crrow]

Build Verification

• cargo check -p rara-kernel ✅
• cargo clippy -p rara-kernel --all-targets --all-features --no-deps -- -D warnings ✅
• cargo test -p rara-kernel ✅ (16 passed, 0 failed)

2 commits on branch:

1. feat(kernel): add proactive signal types, filter, and context pack (#786)
2. feat(kernel): wire proactive signal emit points and time scheduler (#786)