feat(kernel-tui): group sessions into recent/oldish/archived buckets

Author: grypez

packages/kernel-node-runtime/src/daemon/rpc-socket-server.test.ts

@@ -60,10 +60,12 @@ async function sendRequest(
 }
 
 function makeTestSession(overrides: Partial<Session> = {}): Session {
+  const startedAt = overrides.startedAt ?? '2026-01-01T00:00:00.000Z';
   return {
     sessionId: 'alice',
     ocapUrl: 'ocap://test-url',
-    startedAt: '2026-01-01T00:00:00.000Z',
+    startedAt,
+    lastActiveAt: vi.fn().mockReturnValue(startedAt),
     listPending: vi.fn().mockReturnValue([]),
     listHistory: vi.fn().mockReturnValue([]),
     decide: vi.fn(),
@@ -138,7 +140,7 @@ describe('startRpcSocketServer — session.* methods', () => {
     vi.clearAllMocks();
   });
 
-  it('session.create response includes sessionId, ocapUrl, startedAt', async () => {
+  it('session.create response includes sessionId, ocapUrl, startedAt, lastActiveAt', async () => {
     const { startRpcSocketServer } = await import('./rpc-socket-server.ts');
     const socketPath = makeSocketPath();
     const registry = makeTestRegistry();
@@ -157,6 +159,7 @@ describe('startRpcSocketServer — session.* methods', () => {
       sessionId: 'alice',
       ocapUrl: 'ocap://alice',
       startedAt: '2026-01-01T00:00:00.000Z',
+      lastActiveAt: '2026-01-01T00:00:00.000Z',
     });
   });
 
@@ -182,6 +185,7 @@ describe('startRpcSocketServer — session.* methods', () => {
       ocapUrl: 'ocap://alice',
       cwd: '/home/user',
       startedAt: '2026-01-01T00:00:00.000Z',
+      lastActiveAt: '2026-01-01T00:00:00.000Z',
     });
   });
 
@@ -203,13 +207,14 @@ describe('startRpcSocketServer — session.* methods', () => {
     expect(response.result).not.toHaveProperty('cwd');
   });
 
-  it('session.list returns sessions with sessionId, ocapUrl, startedAt', async () => {
+  it('session.list returns sessions with sessionId, ocapUrl, startedAt, lastActiveAt', async () => {
     const { startRpcSocketServer } = await import('./rpc-socket-server.ts');
     const socketPath = makeSocketPath();
     const existing = makeTestSession({
       sessionId: 'alice',
       ocapUrl: 'ocap://alice',
       startedAt: '2026-01-01T00:00:00.000Z',
+      lastActiveAt: vi.fn().mockReturnValue('2026-01-02T00:00:00.000Z'),
     });
     const registry = makeTestRegistry([existing]);
 
@@ -228,11 +233,12 @@ describe('startRpcSocketServer — session.* methods', () => {
         sessionId: 'alice',
         ocapUrl: 'ocap://alice',
         startedAt: '2026-01-01T00:00:00.000Z',
+        lastActiveAt: '2026-01-02T00:00:00.000Z',
       },
     ]);
   });
 
-  it('session.get returns session with sessionId, ocapUrl, startedAt', async () => {
+  it('session.get returns session with sessionId, ocapUrl, startedAt, lastActiveAt', async () => {
     const { startRpcSocketServer } = await import('./rpc-socket-server.ts');
     const socketPath = makeSocketPath();
     const existing = makeTestSession({
@@ -258,6 +264,7 @@ describe('startRpcSocketServer — session.* methods', () => {
       sessionId: 'alice',
       ocapUrl: 'ocap://alice',
       startedAt: '2026-01-01T00:00:00.000Z',
+      lastActiveAt: '2026-01-01T00:00:00.000Z',
     });
   });
 

packages/kernel-node-runtime/src/daemon/rpc-socket-server.ts

@@ -323,6 +323,7 @@ async function handleSessionRequest(
           ocapUrl: session.ocapUrl,
           ...ifDefined({ cwd: session.cwd }),
           startedAt: session.startedAt,
+          lastActiveAt: session.lastActiveAt(),
         });
       }
 
@@ -333,6 +334,7 @@ async function handleSessionRequest(
             ocapUrl: sess.ocapUrl,
             ...ifDefined({ cwd: sess.cwd }),
             startedAt: sess.startedAt,
+            lastActiveAt: sess.lastActiveAt(),
           })),
         );
       }
@@ -349,6 +351,7 @@ async function handleSessionRequest(
           ocapUrl: session.ocapUrl,
           ...ifDefined({ cwd: session.cwd }),
           startedAt: session.startedAt,
+          lastActiveAt: session.lastActiveAt(),
         });
       }
 

packages/kernel-tui/src/components/session-buckets.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest';
+
+import { bucketFor, bucketSessions } from './session-buckets.ts';
+import type { SessionWithRequests } from '../hooks/use-session-data.ts';
+
+function makeSession(
+  overrides: Partial<SessionWithRequests>,
+): SessionWithRequests {
+  return {
+    sessionId: 'sess',
+    ocapUrl: 'ocap://sess',
+    requests: [],
+    ...overrides,
+  };
+}
+
+// A Tuesday at 14:00 local time, well clear of any DST edge.
+const NOW = new Date(2026, 5, 16, 14, 0, 0); // 2026-06-16 (Tue)
+
+describe('bucketFor', () => {
+  it.each([
+    { label: 'same day, hours earlier', offsetMs: -2 * 60 * 60 * 1000 },
+    { label: 'same day, minutes earlier', offsetMs: -10 * 60 * 1000 },
+    { label: 'exactly today midnight', offsetMs: -14 * 60 * 60 * 1000 },
+  ])('classifies $label as recent', ({ offsetMs }) => {
+    const stamp = new Date(NOW.getTime() + offsetMs).toISOString();
+    expect(bucketFor(stamp, NOW)).toBe('recent');
+  });
+
+  it('classifies a late-night session from yesterday within the last 3 hours as recent', () => {
+    // It's 02:00; lastActive was 23:30 yesterday — 2.5h ago.
+    const earlyMorning = new Date(2026, 5, 17, 2, 0, 0);
+    const lateLastNight = new Date(2026, 5, 16, 23, 30, 0).toISOString();
+    expect(bucketFor(lateLastNight, earlyMorning)).toBe('recent');
+  });
+
+  it('classifies yesterday afternoon (more than 3h ago, before today) as oldish', () => {
+    // NOW is Tuesday 14:00; yesterday 14:00 is 24h ago → not recent, but in this week.
+    const yesterdayAfternoon = new Date(2026, 5, 15, 14, 0, 0).toISOString();
+    expect(bucketFor(yesterdayAfternoon, NOW)).toBe('oldish');
+  });
+
+  it('classifies last calendar week as oldish', () => {
+    // NOW is Tuesday 2026-06-16; previous Monday is 2026-06-08.
+    const lastWeek = new Date(2026, 5, 9, 10, 0, 0).toISOString();
+    expect(bucketFor(lastWeek, NOW)).toBe('oldish');
+  });
+
+  it('classifies two weeks ago as archived', () => {
+    const twoWeeksAgo = new Date(2026, 5, 2, 10, 0, 0).toISOString();
+    expect(bucketFor(twoWeeksAgo, NOW)).toBe('archived');
+  });
+
+  it('classifies an undefined timestamp as archived', () => {
+    expect(bucketFor(undefined, NOW)).toBe('archived');
+  });
+
+  it('classifies an unparseable timestamp as archived', () => {
+    expect(bucketFor('not-a-date', NOW)).toBe('archived');
+  });
+});
+
+describe('bucketSessions', () => {
+  it('groups sessions by lastActiveAt with fallback to startedAt', () => {
+    const recent = makeSession({
+      sessionId: 'r',
+      lastActiveAt: new Date(NOW.getTime() - 10 * 60 * 1000).toISOString(),
+    });
+    const earlier = makeSession({
+      sessionId: 'e',
+      lastActiveAt: new Date(2026, 5, 15, 10, 0, 0).toISOString(),
+    });
+    const old = makeSession({
+      sessionId: 'o',
+      // no lastActiveAt, falls back to startedAt
+      startedAt: new Date(2026, 5, 1, 10, 0, 0).toISOString(),
+    });
+    expect(bucketSessions([recent, earlier, old], NOW)).toStrictEqual({
+      recent: [recent],
+      oldish: [earlier],
+      archived: [old],
+    });
+  });
+
+  it('preserves input order within each bucket', () => {
+    const first = makeSession({
+      sessionId: 'a',
+      lastActiveAt: new Date(NOW.getTime() - 10 * 60 * 1000).toISOString(),
+    });
+    const second = makeSession({
+      sessionId: 'b',
+      lastActiveAt: new Date(NOW.getTime() - 30 * 60 * 1000).toISOString(),
+    });
+    const grouped = bucketSessions([first, second], NOW);
+    expect(grouped.recent.map((sess) => sess.sessionId)).toStrictEqual([
+      'a',
+      'b',
+    ]);
+  });
+});

packages/kernel-tui/src/components/session-buckets.ts

@@ -0,0 +1,97 @@
+import type { SessionWithRequests } from '../hooks/use-session-data.ts';
+
+export type Bucket = 'recent' | 'oldish' | 'archived';
+
+const HOURS_3_MS = 3 * 60 * 60 * 1000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Return a Date at the start of the local calendar day containing `date`.
+ *
+ * @param date - The reference Date.
+ * @returns A new Date at 00:00:00.000 local time.
+ */
+function startOfDay(date: Date): Date {
+  const result = new Date(date);
+  result.setHours(0, 0, 0, 0);
+  return result;
+}
+
+/**
+ * Return a Date at the start of the ISO week (Monday 00:00 local) containing
+ * `date`.
+ *
+ * @param date - The reference Date.
+ * @returns A new Date at the start of that week.
+ */
+function startOfWeekMonday(date: Date): Date {
+  const result = startOfDay(date);
+  const day = result.getDay();
+  const offset = day === 0 ? 6 : day - 1;
+  result.setDate(result.getDate() - offset);
+  return result;
+}
+
+/**
+ * Classify a timestamp into a recency bucket.
+ *
+ * - `recent`: lastActive is on today's calendar day OR within the last 3 hours.
+ * - `oldish`: lastActive is within this or last ISO calendar week, but not recent.
+ * - `archived`: anything older, or missing/invalid.
+ *
+ * @param timestamp - ISO 8601 timestamp, or undefined.
+ * @param now - The reference "now" Date.
+ * @returns The bucket name.
+ */
+export function bucketFor(timestamp: string | undefined, now: Date): Bucket {
+  if (timestamp === undefined) {
+    return 'archived';
+  }
+  const stamp = new Date(timestamp);
+  const stampMs = stamp.getTime();
+  if (Number.isNaN(stampMs)) {
+    return 'archived';
+  }
+  const todayStart = startOfDay(now).getTime();
+  const last3hCutoff = now.getTime() - HOURS_3_MS;
+  if (stampMs >= todayStart || stampMs >= last3hCutoff) {
+    return 'recent';
+  }
+  const thisWeekStart = startOfWeekMonday(now).getTime();
+  const lastWeekStart = thisWeekStart - 7 * DAY_MS;
+  if (stampMs >= lastWeekStart) {
+    return 'oldish';
+  }
+  return 'archived';
+}
+
+export type BucketedSessions = {
+  recent: SessionWithRequests[];
+  oldish: SessionWithRequests[];
+  archived: SessionWithRequests[];
+};
+
+/**
+ * Group sessions into recency buckets. Each session's `lastActiveAt` (with
+ * fallback to `startedAt`) is run through {@link bucketFor}; the input order
+ * within each bucket is preserved.
+ *
+ * @param sessions - Sessions in display order (most recently active first).
+ * @param now - The reference "now" Date.
+ * @returns Buckets keyed by name.
+ */
+export function bucketSessions(
+  sessions: SessionWithRequests[],
+  now: Date,
+): BucketedSessions {
+  const buckets: BucketedSessions = {
+    recent: [],
+    oldish: [],
+    archived: [],
+  };
+  for (const session of sessions) {
+    const stamp = session.lastActiveAt ?? session.startedAt;
+    buckets[bucketFor(stamp, now)].push(session);
+  }
+  return buckets;
+}