Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Extend session store with real-time event capture and health invariants

Đang mở
  • Có gì không ổn?
#597 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
25/100
Loại issue
Tính năng
Độ rõ ràng
Cần làm rõ
Mức độ hoạt động
Đình trệ
Công nghệ
rust
Lĩnh vực
backend, observability

Hướng nghiên cứu

Start by reading the existing persistence, search, and session-import paths in terraphim_sessions and the analysis entry points in terraphim-session-analyzer. Trace the listed integration points in terraphim_hooks, terraphim_service, terraphim_multi_agent, terraphim_types, and terraphim_mcp_server, then confirm scope before implementation; done means event capture, typed events, correlation IDs, invariant results, and the listed integrations are covered.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

architecture enhancement multi-agent

Summary

Extend terraphim_sessions and terraphim-session-analyzer with real-time event-level capture, structured event types, and health invariant queries. Not a new crate -- the session store already has persistence, search, and KG enrichment.

Why Not a Separate Event Store?

Originally proposed as a new terraphim_event_store crate. But terraphim_sessions already:

  • Parses session logs into structured records (costs, tool usage, patterns)
  • Uses terraphim_persistence backends (SQLite, DashMap, S3)
  • Supports KG-enriched search via Aho-Corasick automata
  • Has rayon-based parallel processing

A session IS a sequence of events. Building parallel storage is over-engineering.

What's Missing (Gaps to Fill)

1. Real-time capture (not just post-hoc import)

Currently: session logs are imported after the session ends.
Needed: events captured as they happen during a session.

Add a SessionEventEmitter trait:

pub trait SessionEventEmitter: Send + Sync {
    async fn emit(&self, event: SessionEvent) -> Result<()>;
}

Hook into existing infrastructure:

  • terraphim_hooks (PreToolUse, PostToolUse) -> emit events in real-time
  • terraphim_service (search, LLM calls) -> emit events on each operation
  • terraphim_multi_agent (agent decisions) -> emit events per decision
2. Structured event types

Currently: session-analyzer parses free-text logs.
Needed: typed event records for structured queries.

pub enum SessionEvent {
    LlmCall { model: String, tokens_in: u32, tokens_out: u32, cost_usd: f64, latency_ms: u64 },
    SearchExecuted { query: String, results_count: u32, relevance_scores: Vec<f64> },
    HookFired { hook_type: HookType, action: String, result: HookResult },
    Prediction { id: Ulid, source: String, predicted_outcome: String, confidence: f64 },
    Outcome { prediction_id: Ulid, actual_outcome: String, accuracy: f64 },
    ToolUse { tool: String, input_summary: String, success: bool, duration_ms: u64 },
}

These coexist with existing free-text session import -- typed events are a superset.

3. Health invariant queries

Currently: session-analyzer identifies patterns post-hoc.
Needed: automated drift/anomaly detection over rolling windows.

Invariants to detect:

  • Model version drift: responses from unexpected model versions
  • Score distribution shift: ranking scores deviate >2 sigma from rolling baseline
  • Latency degradation: P95 response time exceeds historical threshold
  • Error rate spike: error rate exceeds N% over rolling window
  • Cost anomaly: per-session cost exceeds historical P95

Implementation: add check_invariants() method to session-analyzer that runs over the last N sessions/events and returns violations.

4. Correlation IDs

Currently: events within a session are sequential but not linked.
Needed: link related events (e.g., Prediction -> Outcome, PreToolUse -> PostToolUse for same invocation).

Add correlation_id: Option<Ulid> to SessionEvent. Events in the same logical operation share a correlation ID.

Affected Crates

  • terraphim_sessions (primary -- add real-time emitter, event types)
  • terraphim-session-analyzer (add health invariant queries)
  • terraphim_hooks (emit events via SessionEventEmitter)
  • terraphim_service (emit events for search/LLM calls)
  • terraphim_types (add SessionEvent enum, HookType, etc.)
  • terraphim_mcp_server (expose invariant check results as MCP resource)

Estimated Effort

~1 day for event types + real-time emitter + basic invariants. Ongoing integration per crate.

Part of

Epic #595

Downstream Dependents

  • #598 Budget-aware routing (cost tracking via session events)
  • #599 Enhanced learning capture (learning events are session events)
  • #601 EIDOS episodic reasoning (predictions/outcomes stored as session events)
  • #602 Confidence-driven KG promotion (queries session events for confidence scoring)
Ngôn ngữ chính
Rust
Star
64
Fork
5
Merge trung bình
1 giờ 17 phút
Pull request đã merge (30 ngày)
2

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của terraphim/terraphim-ai

Tất cả issue của terraphim/terraphim-ai

Issue tương tự

Thêm issue về Rust

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.