feat: /sessions timeline command for chronological session bucketing (F4.4) #34

New Issue

2026-04-25T07:02:24+02:00

root commented

2026-04-25 07:02:24 +02:00

Problem Statement

The terraphim-agent-session-search-spec.md (section F4.4 "Session Commands" and the "Interactive Mode" UX preview) mandates a /sessions timeline command for chronological grouping and trend analysis of imported coding-assistant sessions:

/sessions timeline --group-by day --last 30d
/sessions timeline --group-by week

The Phase 3 success criterion claims [x] Timeline and export, yet a repository-wide grep for Timeline / timeline in crates/terraphim_sessions/, crates/terraphim_agent/, and crates/terraphim-session-analyzer/ returns zero hits. Users cannot ask "how many Claude sessions did I have last week" or "show me my coding-assistant activity over the past 30 days" without writing custom queries against the cache. This blocks the dashboards described in the spec's "Reporting & Publishing" section and the historical-trend roadmap item.

Acceptance Criteria

New REPL subcommand SessionsSubcommand::Timeline accepts:
- --group-by day|week|month|hour (default day)
- --last <duration> accepting 7d, 30d, 12w, 6m, 1y (default 30d)
- --source <name> (optional filter, repeatable)
- --since <iso8601> / --until <iso8601> for explicit range bounds (overrides --last)
New service method SessionService::timeline(query: TimelineQuery) -> Result<Timeline> that bins sessions by (group_key, source) using created_at
pub struct Timeline { buckets: Vec<TimelineBucket>, summary: TimelineSummary }
pub struct TimelineBucket { period_start: DateTime<Utc>, period_end: DateTime<Utc>, sessions_by_source: HashMap<String, usize>, total_sessions: usize, total_messages: usize, top_concepts: Vec<String> } (top concepts populated only when enrichment feature is enabled)
Interactive output: ASCII bar chart with one row per period, source-coloured segments, totals column on the right
Robot mode output: RobotResponse<Timeline> with full bucket array; --max-buckets flag caps payload size
Empty range returns success with empty buckets array, exit code 0 (not ERROR_NOT_FOUND)
Unit tests cover: day / week / month bucketing, source filtering, empty range, single bucket, leap-day boundary
Integration test imports three fixture sessions across different days and asserts bucket counts
cargo test -p terraphim_sessions timeline passes
cargo test -p terraphim_agent --features repl-full,repl-sessions sessions_timeline passes
cargo clippy -p terraphim_sessions -p terraphim_agent --features repl-full,repl-sessions -- -D warnings passes

Proposed Approach

Affected crates:

crates/terraphim_sessions/ -- add pub mod timeline with TimelineQuery, Timeline, TimelineBucket, and the service method. Bucket assignment uses chrono::DateTime::date_naive() truncation per group-by mode.
crates/terraphim_agent/src/repl/commands.rs -- extend SessionsSubcommand with Timeline(TimelineArgs) clap variant; reuses an existing parse_duration helper or adds a small one.
crates/terraphim_agent/src/repl/handler.rs -- new handle_sessions_timeline branch that renders the ASCII chart via existing comfy-table styling.

Top-concepts aggregation runs only when the enrichment feature is on, and it reuses SessionConcepts already attached to enriched sessions -- no new KG calls.

Dependencies

None. The session cache and SessionService::list are sufficient to enumerate sessions for bucketing.

Verification

cargo test -p terraphim_sessions timeline
cargo test -p terraphim_agent --features repl-full,repl-sessions sessions_timeline
cargo clippy -p terraphim_sessions -p terraphim_agent --features repl-full,repl-sessions -- -D warnings

Smoke test (after build):

terraphim-agent /sessions timeline --group-by day --last 30d
terraphim-agent /sessions timeline --group-by week --last 12w --source claude-code
terraphim-agent --robot /sessions timeline --group-by month --last 1y

Scope

Single PR, approximately 320 LOC: ~150 LOC bucketing logic + types, ~80 LOC clap variant + ASCII renderer, ~90 LOC tests + fixtures. Trend forecasting, the historical-trends dashboard (Extensibility Roadmap item), and HTML/SVG renderers are out of scope.

## Problem Statement The `terraphim-agent-session-search-spec.md` (section F4.4 "Session Commands" and the "Interactive Mode" UX preview) mandates a `/sessions timeline` command for chronological grouping and trend analysis of imported coding-assistant sessions: ``` /sessions timeline --group-by day --last 30d /sessions timeline --group-by week ``` The Phase 3 success criterion claims `[x] Timeline and export`, yet a repository-wide grep for `Timeline` / `timeline` in `crates/terraphim_sessions/`, `crates/terraphim_agent/`, and `crates/terraphim-session-analyzer/` returns zero hits. Users cannot ask "how many Claude sessions did I have last week" or "show me my coding-assistant activity over the past 30 days" without writing custom queries against the cache. This blocks the dashboards described in the spec's "Reporting & Publishing" section and the historical-trend roadmap item. ## Acceptance Criteria - [ ] New REPL subcommand `SessionsSubcommand::Timeline` accepts: - `--group-by day|week|month|hour` (default `day`) - `--last <duration>` accepting `7d`, `30d`, `12w`, `6m`, `1y` (default `30d`) - `--source <name>` (optional filter, repeatable) - `--since <iso8601>` / `--until <iso8601>` for explicit range bounds (overrides `--last`) - [ ] New service method `SessionService::timeline(query: TimelineQuery) -> Result<Timeline>` that bins sessions by `(group_key, source)` using `created_at` - [ ] `pub struct Timeline { buckets: Vec<TimelineBucket>, summary: TimelineSummary }` - [ ] `pub struct TimelineBucket { period_start: DateTime<Utc>, period_end: DateTime<Utc>, sessions_by_source: HashMap<String, usize>, total_sessions: usize, total_messages: usize, top_concepts: Vec<String> }` (top concepts populated only when `enrichment` feature is enabled) - [ ] Interactive output: ASCII bar chart with one row per period, source-coloured segments, totals column on the right - [ ] Robot mode output: `RobotResponse<Timeline>` with full bucket array; `--max-buckets` flag caps payload size - [ ] Empty range returns success with empty buckets array, exit code 0 (not `ERROR_NOT_FOUND`) - [ ] Unit tests cover: day / week / month bucketing, source filtering, empty range, single bucket, leap-day boundary - [ ] Integration test imports three fixture sessions across different days and asserts bucket counts - [ ] `cargo test -p terraphim_sessions timeline` passes - [ ] `cargo test -p terraphim_agent --features repl-full,repl-sessions sessions_timeline` passes - [ ] `cargo clippy -p terraphim_sessions -p terraphim_agent --features repl-full,repl-sessions -- -D warnings` passes ## Proposed Approach Affected crates: - `crates/terraphim_sessions/` -- add `pub mod timeline` with `TimelineQuery`, `Timeline`, `TimelineBucket`, and the service method. Bucket assignment uses `chrono::DateTime::date_naive()` truncation per group-by mode. - `crates/terraphim_agent/src/repl/commands.rs` -- extend `SessionsSubcommand` with `Timeline(TimelineArgs)` clap variant; reuses an existing `parse_duration` helper or adds a small one. - `crates/terraphim_agent/src/repl/handler.rs` -- new `handle_sessions_timeline` branch that renders the ASCII chart via existing `comfy-table` styling. Top-concepts aggregation runs only when the `enrichment` feature is on, and it reuses `SessionConcepts` already attached to enriched sessions -- no new KG calls. ## Dependencies None. The session cache and `SessionService::list` are sufficient to enumerate sessions for bucketing. ## Verification ``` cargo test -p terraphim_sessions timeline cargo test -p terraphim_agent --features repl-full,repl-sessions sessions_timeline cargo clippy -p terraphim_sessions -p terraphim_agent --features repl-full,repl-sessions -- -D warnings ``` Smoke test (after build): ``` terraphim-agent /sessions timeline --group-by day --last 30d terraphim-agent /sessions timeline --group-by week --last 12w --source claude-code terraphim-agent --robot /sessions timeline --group-by month --last 1y ``` ## Scope Single PR, approximately 320 LOC: ~150 LOC bucketing logic + types, ~80 LOC clap variant + ASCII renderer, ~90 LOC tests + fixtures. Trend forecasting, the historical-trends dashboard (Extensibility Roadmap item), and HTML/SVG renderers are out of scope.

product-owner referenced this issue

2026-04-27 07:00:23 +02:00

feat: wire ExitCode into main() return for f1.2 robot exit code contract #35

product-owner added a new dependency 2026-04-27 11:03:37 +02:00

#26 feat: redact api keys/secrets/JWTs during session import (Privacy)

product-owner referenced this issue

2026-04-27 11:04:34 +02:00

feat: wire ExitCode into main() return for f1.2 robot exit code contract #35

root referenced this issue

2026-04-27 13:05:00 +02:00

feat: wire ExitCode into main() return for f1.2 robot exit code contract #35

product-owner referenced this issue