V7 Quickstart

Documentation for Sessions

Session Tracking v7.0 - Quick Start Guide

What You Have Now

A production-ready MongoDB-first session tracking system that replaces the old JSON-based v6.0 with:

✅ No more race conditions - Optimistic locking prevents concurrent update conflicts ✅ Graceful degradation - Works even when MongoDB is down (falls back to JSON cache) ✅ Circuit breaker protection - Automatically handles failures without cascading ✅ Atomic operations - MongoDB transactions ensure data consistency ✅ 190+ tests - Comprehensive unit and integration test coverage

Architecture Overview

┌──────────────────────────────────────────────────────────────────┐
│                    MongoDB (Source of Truth)                      │
│  - sessions collection (CRUD with optimistic locking)            │
│  - workspace_state collection (active session per workspace)     │
└────────────────────────┬─────────────────────────────────────────┘
                         │
                         ↓ (event-driven sync, debounced 30s)
┌──────────────────────────────────────────────────────────────────┐
│               JSON Cache (Read-Only, Auto-Generated)              │
│  - sessions/sessions-history/{workspace}/history.json            │
│  - sessions/active.json                                          │
└──────────────────────────────────────────────────────────────────┘

Libraries Created

1. `@libs-api/session-repository`

MongoDB data access layer

SessionRepository - CRUD operations with optimistic locking
WorkspaceStateRepository - Workspace state management
SessionDocument schema - MongoDB document structure
120+ unit tests

Example:

import { SessionRepository } from '@libs-api/session-repository';

// Create session
await sessionRepo.create({
  sessionID: 'editor2-22.43',
  workspace: 'editor2',
  sessionNumber: 22,
  subSessionNumber: 43,
  title: 'Fix bug in validator',
  platform: 'cursor',
});

// Update with optimistic locking
await sessionRepo.update('editor2-22.43', 'editor2', {
  title: 'Updated title',
  version: 1, // Must match current version
});

// Version conflict → ConflictException (retry with new version)

2. `@libs-api/session-service`

Business logic with circuit breaker

SessionService - Wraps repository with circuit breaker protection
SessionValidatorService - Critical vs warning level validations
SessionHealthService - Health monitoring and degraded mode
70+ integration tests

Example:

import { SessionService } from '@libs-api/session-service';

// All operations protected by circuit breaker
sessionService.findSessionById('editor2-22.43', 'editor2')
  .subscribe({
    next: (session) => console.log(session),
    error: (err) => {
      // Circuit breaker open → fallback to JSON cache
      console.error('MongoDB unavailable, using cache');
    },
  });

// Validation with degraded mode
validatorService.configure({ degradedMode: true });
validatorService.validateSession(session).subscribe(result => {
  // In degraded mode: critical errors become warnings
  // Work continues even with validation issues
  console.log('Passed:', result.passed);
  console.log('Warnings:', result.warnings);
});

3. `@libs-api/session-json-cache`

Atomic file writes and sync

AtomicFileWriter - Safe JSON writes (temp + rename pattern)
SessionSyncService - MongoDB → JSON cache generation

Example:

import { SessionSyncService } from '@libs-api/session-json-cache';

// Manual sync
await syncService.sync({ workspace: 'editor2' });

// Event-driven sync (auto-triggers after updates)
syncService.configure({
  enableEventDrivenSync: true,
  syncDebounceTime: 30000, // 30 seconds
});

syncService.triggerSync('editor2', 'Session updated');

CLI Tools

1. Migration Script (`session-migration-v7.ts`)

Migrate your existing v6.0 JSON files to v7.0 MongoDB

# Dry run (validate without changes)
node tools/scripts/database/session-migration-v7.ts --dry-run

# Migrate specific workspace
node tools/scripts/database/session-migration-v7.ts --workspace=editor2

# Migrate all workspaces
node tools/scripts/database/session-migration-v7.ts

# Rollback (delete MongoDB data for workspace)
node tools/scripts/database/session-migration-v7.ts --workspace=editor2 --rollback

Features:

✅ Batch processing (100 sessions at a time)
✅ MongoDB transactions (all-or-nothing)
✅ Integrity validation
✅ Rollback capability
✅ Dry-run mode

2. Sync Tool (`session-sync-v7.ts`)

Manually trigger MongoDB → JSON cache sync

# Sync all workspaces
node tools/scripts/database/session-sync-v7.ts

# Sync specific workspace
node tools/scripts/database/session-sync-v7.ts --workspace=editor2

# Dry run
node tools/scripts/database/session-sync-v7.ts --dry-run

# Force sync (even if cache is fresh)
node tools/scripts/database/session-sync-v7.ts --force

# Show cache statistics
node tools/scripts/database/session-sync-v7.ts --stats

Getting Started (3 Steps)

Step 1: Set MongoDB Connection

Ensure your MongoDB connection is configured:

# .env file
MONGO_URI_AGENTS=mongodb://localhost:27017/agents

Step 2: Run Migration

# Validate first (dry run)
node tools/scripts/database/session-migration-v7.ts --dry-run

# If validation passes, run actual migration
node tools/scripts/database/session-migration-v7.ts

Expected output:

🚀 Session Migration v7.0
========================

Found 1 workspace(s) to migrate:

📦 Migrating workspace: editor2
──────────────────────────────────────────────────
Found 43 session(s)

  Batch 1/1 (43 sessions)
    ✓ editor2-22.1 migrated
    ✓ editor2-22.2 migrated
    ...
  ✓ Workspace state created
✅ Workspace editor2 migrated successfully

==================================================
📊 Migration Summary
==================================================
Workspaces: 1
Total Sessions: 43
✓ Migrated: 43
⏭️  Skipped: 0
❌ Failed: 0
Duration: 2.34s

✅ Migration completed successfully!

Step 3: Sync JSON Caches

# Generate JSON cache files from MongoDB
node tools/scripts/database/session-sync-v7.ts

Expected output:

🔄 Session Sync v7.0
===================

📊 Sync Results
──────────────────────────────────────────────────
Status: ✅ Completed
Reason: Sync completed
Files Written: 2
Duration: 0.45s

📝 Files Updated:
  ✓ /path/to/sessions/sessions-history/editor2/history.json
  ✓ /path/to/sessions/active.json

✅ Sync completed successfully!

Degraded Mode (Graceful Failures)

The system automatically handles MongoDB failures:

// MongoDB goes down...
sessionService.findSessionById('editor2-22.43', 'editor2')
  .subscribe({
    next: (session) => {
      // Falls back to JSON cache automatically
      console.log('Using cached data:', session);
    },
  });

// Circuit breaker metrics
sessionService.getDegradedModeState().subscribe(state => {
  console.log('Degraded:', state.isDegraded);
  console.log('Reason:', state.reason);
  console.log('Circuit State:', state.circuitState);
});

// Health monitoring
healthService.getSystemHealth().subscribe(health => {
  console.log('Status:', health.status); // 'healthy' | 'degraded' | 'unhealthy'
  console.log('MongoDB Connected:', health.mongoDbConnected);
  console.log('Recommendations:', health.recommendations);
});

Optimistic Locking (Prevent Race Conditions)

The Problem (v6.0):

Agent A reads session (version 1)
Agent B reads session (version 1)
Agent A writes → version 2 ✅
Agent B writes → overwrites A's changes ❌ (race condition)

The Solution (v7.0):

// Agent A
const session = await repo.findById('editor2-22.43', 'editor2'); // version: 1
await repo.update('editor2-22.43', 'editor2', {
  title: 'Agent A update',
  version: 1, // ✅ Succeeds → version becomes 2
});

// Agent B (concurrent)
const session = await repo.findById('editor2-22.43', 'editor2'); // version: 1
await repo.update('editor2-22.43', 'editor2', {
  title: 'Agent B update',
  version: 1, // ❌ Throws ConflictException (version is now 2)
});

// Agent B retries with current version
const updated = await repo.findById('editor2-22.43', 'editor2'); // version: 2
await repo.update('editor2-22.43', 'editor2', {
  title: 'Agent B update',
  version: 2, // ✅ Succeeds → version becomes 3
});

Testing

# Run all tests
npm test

# Run repository tests
npm test -- session-repository

# Run service tests
npm test -- session-service

# Coverage report
npm test -- --coverage

Monitoring & Observability

// Circuit breaker metrics
const metrics = circuitBreaker.getAllMetrics();
console.log('Session operations:', metrics['session:findById']);
console.log('Success rate:', metrics['session:findById'].successRate);

// Reset circuit breaker (manual recovery)
sessionService.resetCircuit('session:findById');

// System health
healthService.getSystemHealth().subscribe(health => {
  console.log('Uptime:', healthService.getFormattedUptime());
  console.log('Components:', health.components);
});

What's Next?

The system is ready to use. Phases 1-5 are complete:

✅ Phase 1: Repository layer (MongoDB CRUD) ✅ Phase 2: Service layer (Circuit breaker + validation) ✅ Phase 3: JSON cache layer (Atomic writes + sync) ✅ Phase 4: Migration script (v6.0 → v7.0) ✅ Phase 5: CLI tools (Sync + migration)

Optional improvements (not blocking):

Phase 6: Performance tests (1000+ sessions, < 100ms latency)
Phase 7: Production monitoring dashboard

Troubleshooting

Migration fails with "Duplicate key error"

Cause: Sessions already exist in MongoDB Solution: Use --rollback to clean up, then retry

node tools/scripts/database/session-migration-v7.ts --workspace=editor2 --rollback
node tools/scripts/database/session-migration-v7.ts --workspace=editor2

Circuit breaker stuck open

Cause: Too many MongoDB failures Solution: Reset circuit breaker

sessionService.resetAllCircuits();

JSON cache is stale

Cause: Sync hasn't run recently Solution: Manual sync

node tools/scripts/database/session-sync-v7.ts --force

Support

For issues or questions:

Check logs in MongoDB collections
Verify MongoDB connection (MONGO_URI_AGENTS)
Run migration dry-run to validate data
Check circuit breaker states with health service

Built with: MongoDB, Mongoose, NestJS, RxJS, Circuit Breaker, Optimistic Locking Test Coverage: 190+ tests (unit + integration) Production Ready: ✅

Session Tracking v7.0 - Quick Start Guide

What You Have Now

Architecture Overview

Libraries Created

1. @libs-api/session-repository

2. @libs-api/session-service

3. @libs-api/session-json-cache

CLI Tools

1. Migration Script (session-migration-v7.ts)

2. Sync Tool (session-sync-v7.ts)

Getting Started (3 Steps)

Step 1: Set MongoDB Connection

Step 2: Run Migration

Step 3: Sync JSON Caches

Degraded Mode (Graceful Failures)

Optimistic Locking (Prevent Race Conditions)

Testing

Monitoring & Observability

What's Next?

Troubleshooting

Migration fails with "Duplicate key error"

Circuit breaker stuck open

JSON cache is stale

Support

1. `@libs-api/session-repository`

2. `@libs-api/session-service`

3. `@libs-api/session-json-cache`

1. Migration Script (`session-migration-v7.ts`)

2. Sync Tool (`session-sync-v7.ts`)