byterover-cli 1.0.3 → 1.0.5

package/README.md

@@ -1,6 +1,6 @@
 # ByteRover CLI
 
-Command-line interface for ByteRover, featuring an interactive REPL with a modern terminal UI for managing your project's context tree and memory storage.
+Command-line interface for ByteRover, featuring an interactive REPL with a modern React/Ink terminal UI for managing your project's context tree and knowledge storage. Seamlessly integrate with AI coding agents like Claude Code, Cursor, Windsurf, and GitHub Copilot.
 
 [![Version](https://img.shields.io/npm/v/byterover-cli.svg)](https://npmjs.org/package/byterover-cli)
 [![Downloads/week](https://img.shields.io/npm/dw/byterover-cli.svg)](https://npmjs.org/package/byterover-cli)
@@ -15,6 +15,7 @@ Command-line interface for ByteRover, featuring an interactive REPL with a moder
 * [Slash Commands Reference](#slash-commands-reference)
 * [Authentication](#authentication)
 * [Configuration](#configuration)
+* [Troubleshooting](#troubleshooting)
 * [Getting Help](#getting-help)
 
 ## Installation
@@ -90,6 +91,16 @@ brv
 
 Running `brv` without arguments starts the interactive REPL. The REPL requires an interactive terminal (TTY).
 
+### TUI Features
+
+The terminal UI includes:
+
+- **Tab Navigation**: Switch between Chat and Activity views using `Tab`
+- **Command Completion**: Type `/` to see available commands with auto-completion
+- **Activity Log**: Real-time task status and execution progress
+- **Streaming Output**: Live responses from AI-powered operations
+- **File References**: Type `@` in curate mode to browse and attach files
+
 ### Using Commands
 
 In the REPL, use slash commands (commands prefixed with `/`) to interact with ByteRover:
@@ -104,24 +115,33 @@ Commands support tab completion for quick navigation.
 
 ## What is Context Tree?
 
-The **Context Tree** is ByteRover's structured memory system that helps you and your coding agents organize, store, and retrieve project knowledge efficiently.
+The **Context Tree** is ByteRover's structured knowledge system that helps you and your AI coding agents organize, store, and retrieve project context efficiently.
 
 ### Why Use Context Tree?
 
 - **Organized Knowledge**: Structure your project knowledge by domain and topic
 - **Easy Retrieval**: Find relevant context quickly when you need it
 - **Persistent Memory**: Maintain project-specific knowledge across sessions
-- **Agent-Friendly**: Works seamlessly with coding agents like Claude Code, Cursor, and others
-- **Version Control**: Push and sync your context to ByteRover's cloud storage
+- **Agent-Friendly**: Works seamlessly with AI coding agents like Claude Code, Cursor, Windsurf, and GitHub Copilot
+- **Cloud Sync**: Push and sync your context tree to ByteRover's cloud storage for backup and team collaboration
+- **Dynamic Domains**: Automatically creates new domains as your knowledge grows
 
 ### How It Works
 
 The context tree organizes knowledge into:
-- **Domains**: High-level categories (e.g., Architecture, API, Frontend)
+- **Domains**: High-level categories (e.g., Architecture, API, Frontend) — created automatically or manually
 - **Topics**: Specific subjects within domains (e.g., Authentication, Components)
 - **Context Files**: Markdown files containing your actual knowledge
 
-For comprehensive instructions for coding agents, use `/gen-rules` to generate rule files.
+### Integrating with Coding Agents
+
+Use `/gen-rules` to generate rule instruction files that help your AI coding agents understand and work with ByteRover:
+
+```
+/gen-rules
+```
+
+This creates agent-specific rule files (e.g., `CLAUDE.md`, `.cursorrules`) that instruct the agent how to read from and contribute to your context tree.
 
 ## Slash Commands Reference
 
@@ -150,8 +170,8 @@ For comprehensive instructions for coding agents, use `/gen-rules` to generate r
 
 | Command | Description |
 |---------|-------------|
-| `/push [-b branch] [-y]` | Push context tree to ByteRover memory storage |
-| `/pull [-b branch]` | Pull context tree from ByteRover memory storage |
+| `/push [-b branch] [-y]` | Push context tree to ByteRover cloud storage |
+| `/pull [-b branch]` | Pull context tree from ByteRover cloud storage |
 
 **Options:**
 - `-b, --branch <name>`: ByteRover branch name (default: `main`)
@@ -182,12 +202,23 @@ For comprehensive instructions for coding agents, use `/gen-rules` to generate r
 
 | Command | Description |
 |---------|-------------|
-| `/gen-rules` | Generate rule instructions for coding agents |
-| `/clear [-y] [directory]` | Reset context tree to default domains |
+| `/gen-rules` | Generate rule files for AI coding agents (Claude Code, Cursor, etc.) |
+| `/reset [-y] [directory]` | Reset context tree to default domains |
 
-**Clear options:**
+**Reset options:**
+- `-y, --yes`: Skip confirmation prompt
+
+### Session Management
+
+| Command | Description |
+|---------|-------------|
+| `/new [-y]` | Start a fresh session (ends current session, clears conversation) |
+
+**Options:**
 - `-y, --yes`: Skip confirmation prompt
 
+**Note:** This command does NOT affect the context tree—it only clears the conversation history and starts a new session.
+
 ### Project Setup
 
 | Command | Description |
@@ -232,6 +263,16 @@ When you run `/init`, a configuration file is created at `.brv/config.json` in y
 - **User information**: Your user ID and email
 - **Project settings**: Project-specific configuration
 
+### Global Configuration
+
+User-level configuration is stored at `~/.config/brv/`:
+
+```
+~/.config/brv/
+├── config.json    # Global settings and device ID
+└── logs/          # Session logs for debugging
+```
+
 ### Context Tree Structure
 
 The context tree is stored in `.brv/context-tree/`:
@@ -255,7 +296,29 @@ The context tree is stored in `.brv/context-tree/`:
         └── context.md
 ```
 
-**Note**: When you run `/push`, your context tree is uploaded to ByteRover's memory storage for version control and team collaboration.
+**Note**: When you run `/push`, your context tree is uploaded to ByteRover's cloud storage for version control and team collaboration.
+
+## Troubleshooting
+
+### Session Logs
+
+If you encounter issues, session logs are stored at `~/.config/brv/logs/`. Each session creates a timestamped log file (e.g., `brv-2024-01-15T10-30-00.log`) that can help diagnose problems.
+
+### Instance Lock
+
+ByteRover CLI ensures only one instance runs per project folder. If you see an "instance already running" message:
+
+1. Check for another terminal with `brv` running in the same directory
+2. If no other instance is visible, the lock file may be stale — it will auto-release on the next start
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "REPL requires an interactive terminal" | Run `brv` directly in a terminal, not through piped commands |
+| Authentication expires frequently | Run `/login` to refresh your session |
+| Context tree not syncing | Check `/status` for sync status, then try `/push` or `/pull` |
+| Rule files not generated | Ensure you're in a project directory with `.brv/` initialized |
 
 ## Getting Help
 

package/dist/commands/curate.js

@@ -1,7 +1,7 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { isDevelopment } from '../config/environment.js';
 import { FileGlobalConfigStore } from '../infra/storage/file-global-config-store.js';
-import { KeychainTokenStore } from '../infra/storage/keychain-token-store.js';
+import { createTokenStore } from '../infra/storage/token-store.js';
 import { OclifTerminal } from '../infra/terminal/oclif-terminal.js';
 import { MixpanelTrackingService } from '../infra/tracking/mixpanel-tracking-service.js';
 import { CurateUseCase } from '../infra/usecase/curate-use-case.js';
@@ -14,7 +14,7 @@ export default class Curate extends Command {
     };
     static description = `Curate context to the context tree (connects to running brv instance)
 
-Requires a running brv instance. Start one with: brv start
+Requires a running brv instance. Start one with: brv
 
 Good examples:
 - "Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via authMiddleware.ts"
@@ -49,7 +49,7 @@ Bad examples:
             : {}),
     };
     createUseCase() {
-        const tokenStore = new KeychainTokenStore();
+        const tokenStore = createTokenStore();
         const globalConfigStore = new FileGlobalConfigStore();
         const terminal = new OclifTerminal(this);
         const trackingService = new MixpanelTrackingService({ globalConfigStore, tokenStore });

package/dist/commands/main.d.ts

@@ -14,4 +14,17 @@ export default class Main extends Command {
      */
     static hidden: boolean;
     run(): Promise<void>;
+    /**
+     * Resolve session ID for the agent.
+     *
+     * Strategy:
+     * 1. Check for active session in .brv/sessions/active.json
+     * 2. If active session exists and is valid (not stale), resume it
+     * 3. If stale (process crashed), mark as interrupted and create new
+     * 4. If no active session, create new session
+     * 5. Run session cleanup on startup
+     *
+     * @returns Session ID to use
+     */
+    private resolveSessionId;
 }

package/dist/commands/main.js

@@ -1,12 +1,15 @@
 import { Command } from '@oclif/core';
+import { randomUUID } from 'node:crypto';
+import { DEFAULT_SESSION_RETENTION } from '../core/domain/cipher/session/session-metadata.js';
+import { SessionMetadataStore } from '../infra/cipher/session/session-metadata-store.js';
 import { ProjectConfigStore } from '../infra/config/file-config-store.js';
 import { getProcessManager } from '../infra/process/index.js';
 import { startRepl } from '../infra/repl/repl-startup.js';
 import { FileGlobalConfigStore } from '../infra/storage/file-global-config-store.js';
 import { FileOnboardingPreferenceStore } from '../infra/storage/file-onboarding-preference-store.js';
-import { KeychainTokenStore } from '../infra/storage/keychain-token-store.js';
+import { createTokenStore } from '../infra/storage/token-store.js';
 import { MixpanelTrackingService } from '../infra/tracking/mixpanel-tracking-service.js';
-import { initSessionLog } from '../utils/process-logger.js';
+import { initSessionLog, processManagerLog } from '../utils/process-logger.js';
 /**
  * Main command - Entry point for ByteRover CLI.
  *
@@ -30,10 +33,14 @@ export default class Main extends Command {
             this.log("Run 'brv --help' for available commands.");
             return;
         }
+        // Resolve session ID (auto-resume or create new)
+        const sessionId = await this.resolveSessionId();
+        processManagerLog(`Session ID resolved: ${sessionId}`);
         // Start Transport and Agent processes (v0.5.0 architecture)
+        // Pass session ID to Agent via environment variable
         const processManager = getProcessManager();
-        await processManager.start();
-        const tokenStore = new KeychainTokenStore();
+        await processManager.start({ sessionId });
+        const tokenStore = createTokenStore();
         const globalConfigStore = new FileGlobalConfigStore();
         const trackingService = new MixpanelTrackingService({ globalConfigStore, tokenStore });
         const onboardingPreferenceStore = new FileOnboardingPreferenceStore();
@@ -52,4 +59,48 @@ export default class Main extends Command {
             await processManager.stop();
         }
     }
+    /**
+     * Resolve session ID for the agent.
+     *
+     * Strategy:
+     * 1. Check for active session in .brv/sessions/active.json
+     * 2. If active session exists and is valid (not stale), resume it
+     * 3. If stale (process crashed), mark as interrupted and create new
+     * 4. If no active session, create new session
+     * 5. Run session cleanup on startup
+     *
+     * @returns Session ID to use
+     */
+    async resolveSessionId() {
+        const sessionStore = new SessionMetadataStore();
+        // Run cleanup on startup (async, don't wait)
+        sessionStore.cleanupSessions(DEFAULT_SESSION_RETENTION).catch((error) => {
+            processManagerLog(`Session cleanup failed: ${error}`);
+        });
+        // Check for active session
+        const activeSession = await sessionStore.getActiveSession();
+        if (activeSession) {
+            // Check if the active session is stale (process not running)
+            const isStale = await sessionStore.isActiveSessionStale();
+            if (isStale) {
+                // Mark the old session as interrupted
+                processManagerLog(`Active session ${activeSession.sessionId} is stale, marking as interrupted`);
+                await sessionStore.markSessionInterrupted(activeSession.sessionId);
+            }
+            else {
+                // Valid active session - resume it
+                processManagerLog(`Resuming active session: ${activeSession.sessionId}`);
+                return activeSession.sessionId;
+            }
+        }
+        // Create new session
+        const newSessionId = `agent-session-${randomUUID()}`;
+        processManagerLog(`Creating new session: ${newSessionId}`);
+        // Save session metadata
+        const metadata = sessionStore.createSessionMetadata(newSessionId);
+        await sessionStore.saveSession(metadata);
+        // Set as active session
+        await sessionStore.setActiveSession(newSessionId);
+        return newSessionId;
+    }
 }

package/dist/commands/query.js

@@ -1,7 +1,7 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { isDevelopment } from '../config/environment.js';
 import { FileGlobalConfigStore } from '../infra/storage/file-global-config-store.js';
-import { KeychainTokenStore } from '../infra/storage/keychain-token-store.js';
+import { createTokenStore } from '../infra/storage/token-store.js';
 import { OclifTerminal } from '../infra/terminal/oclif-terminal.js';
 import { MixpanelTrackingService } from '../infra/tracking/mixpanel-tracking-service.js';
 import { QueryUseCase } from '../infra/usecase/query-use-case.js';
@@ -14,7 +14,7 @@ export default class Query extends Command {
     };
     static description = `Query and retrieve information from the context tree (connects to running brv instance)
 
-Requires a running brv instance. Start one with: brv start
+Requires a running brv instance. Start one with: brv
 
 Good:
 - "How is user authentication implemented?"
@@ -40,7 +40,7 @@ Bad:
     };
     static strict = false;
     createUseCase() {
-        const tokenStore = new KeychainTokenStore();
+        const tokenStore = createTokenStore();
         const globalConfigStore = new FileGlobalConfigStore();
         const trackingService = new MixpanelTrackingService({ globalConfigStore, tokenStore });
         return new QueryUseCase({

package/dist/commands/status.js

@@ -3,7 +3,7 @@ import { ProjectConfigStore } from '../infra/config/file-config-store.js';
 import { FileContextTreeService } from '../infra/context-tree/file-context-tree-service.js';
 import { FileContextTreeSnapshotService } from '../infra/context-tree/file-context-tree-snapshot-service.js';
 import { FileGlobalConfigStore } from '../infra/storage/file-global-config-store.js';
-import { KeychainTokenStore } from '../infra/storage/keychain-token-store.js';
+import { createTokenStore } from '../infra/storage/token-store.js';
 import { OclifTerminal } from '../infra/terminal/oclif-terminal.js';
 import { MixpanelTrackingService } from '../infra/tracking/mixpanel-tracking-service.js';
 import { StatusUseCase } from '../infra/usecase/status-use-case.js';
@@ -29,7 +29,7 @@ export default class Status extends Command {
         }),
     };
     createUseCase() {
-        const tokenStore = new KeychainTokenStore();
+        const tokenStore = createTokenStore();
         const globalConfigStore = new FileGlobalConfigStore();
         const trackingService = new MixpanelTrackingService({ globalConfigStore, tokenStore });
         const contextTreeSnapshotService = new FileContextTreeSnapshotService();

package/dist/constants.d.ts

@@ -6,6 +6,7 @@ export declare const BRV_CONFIG_VERSION = "0.0.1";
 export declare const GLOBAL_CONFIG_DIR = "brv";
 export declare const GLOBAL_CONFIG_FILE = "config.json";
 export declare const GLOBAL_CONFIG_VERSION = "0.0.1";
+export declare const GLOBAL_DATA_DIR = "brv";
 export declare const ACE_DIR = "ace";
 export declare const PROJECT = "byterover";
 export declare const CONTEXT_TREE_DIR = "context-tree";
@@ -33,4 +34,4 @@ export declare const TRANSPORT_RECONNECTION_ATTEMPTS = 30;
 export declare const TRANSPORT_PING_INTERVAL_MS = 5000;
 export declare const TRANSPORT_PING_TIMEOUT_MS = 10000;
 export declare const TRANSPORT_DEFAULT_TRANSPORTS: ('polling' | 'websocket')[];
-export declare const DEFAULT_LLM_MODEL = "gemini-2.5-pro";
+export declare const DEFAULT_LLM_MODEL = "gemini-3-flash-preview";

package/dist/constants.js

@@ -7,6 +7,9 @@ export const BRV_CONFIG_VERSION = '0.0.1';
 export const GLOBAL_CONFIG_DIR = 'brv';
 export const GLOBAL_CONFIG_FILE = 'config.json';
 export const GLOBAL_CONFIG_VERSION = '0.0.1';
+// Global data directory name (for XDG_DATA_HOME - secrets, credentials, cache)
+// Same value as GLOBAL_CONFIG_DIR but different semantic purpose
+export const GLOBAL_DATA_DIR = 'brv';
 // ACE directory structure constants
 export const ACE_DIR = 'ace';
 export const PROJECT = 'byterover';
@@ -40,4 +43,4 @@ export const TRANSPORT_PING_TIMEOUT_MS = 10_000; // 10s timeout - avoid false di
 // HTTP polling may be blocked by IDE sandboxes causing "xhr poll error"
 export const TRANSPORT_DEFAULT_TRANSPORTS = ['websocket'];
 // LLM Model defaults
-export const DEFAULT_LLM_MODEL = 'gemini-2.5-pro';
+export const DEFAULT_LLM_MODEL = 'gemini-3-flash-preview';

package/dist/core/domain/cipher/file-system/types.d.ts

@@ -146,6 +146,8 @@ export interface FileContent {
     totalLines: number;
     /** Whether content was truncated due to size/line limits */
     truncated: boolean;
+    /** Number of lines that were truncated due to excessive length */
+    truncatedLineCount?: number;
 }
 /**
  * Result of a file write operation.

package/dist/core/domain/cipher/llm/registry.js

@@ -27,19 +27,54 @@ export const LLM_REGISTRY = {
         supportedFileTypes: [],
     },
     gemini: {
-        defaultModel: 'gemini-2.5-flash',
+        defaultModel: 'gemini-3-flash-preview',
         models: [
-            // Gemini 2.5 series
+            // Gemini 3 series (Preview)
             {
                 capabilities: {
                     supportsAudio: true,
                     supportsImages: true,
+                    supportsMultimodalFunctionResponse: true,
                     supportsPdf: true,
                     supportsStreaming: true,
                     supportsThinking: true,
                 },
                 charsPerToken: 4,
                 default: true,
+                displayName: 'Gemini 3 Flash (Preview)',
+                maxInputTokens: 1_000_000,
+                maxOutputTokens: 8192,
+                name: 'gemini-3-flash-preview',
+                pricing: { inputPerM: 0.075, outputPerM: 0.3 },
+                supportedFileTypes: ['image', 'pdf', 'audio'],
+            },
+            {
+                capabilities: {
+                    supportsAudio: true,
+                    supportsImages: true,
+                    supportsMultimodalFunctionResponse: true,
+                    supportsPdf: true,
+                    supportsStreaming: true,
+                    supportsThinking: true,
+                },
+                charsPerToken: 4,
+                displayName: 'Gemini 3 Pro (Preview)',
+                maxInputTokens: 1_000_000,
+                maxOutputTokens: 8192,
+                name: 'gemini-3-pro-preview',
+                pricing: { inputPerM: 1.25, outputPerM: 5 },
+                supportedFileTypes: ['image', 'pdf', 'audio'],
+            },
+            // Gemini 2.5 series
+            {
+                capabilities: {
+                    supportsAudio: true,
+                    supportsImages: true,
+                    supportsPdf: true,
+                    supportsStreaming: true,
+                    supportsThinking: true,
+                },
+                charsPerToken: 4,
                 displayName: 'Gemini 2.5 Flash',
                 maxInputTokens: 1_000_000,
                 maxOutputTokens: 8192,
@@ -47,6 +82,22 @@ export const LLM_REGISTRY = {
                 pricing: { inputPerM: 0.075, outputPerM: 0.3 },
                 supportedFileTypes: ['image', 'pdf', 'audio'],
             },
+            {
+                capabilities: {
+                    supportsAudio: true,
+                    supportsImages: true,
+                    supportsPdf: true,
+                    supportsStreaming: true,
+                    supportsThinking: true,
+                },
+                charsPerToken: 4,
+                displayName: 'Gemini 2.5 Pro',
+                maxInputTokens: 1_000_000,
+                maxOutputTokens: 8192,
+                name: 'gemini-2.5-pro',
+                pricing: { inputPerM: 1.25, outputPerM: 5 },
+                supportedFileTypes: ['image', 'pdf', 'audio'],
+            },
             // Gemini 1.5 series
             {
                 capabilities: {

package/dist/core/domain/cipher/llm/types.d.ts

@@ -28,6 +28,8 @@ export interface ModelCapabilities {
     supportsAudio: boolean;
     /** Whether the model supports image input */
     supportsImages: boolean;
+    /** Whether the model supports multimodal data in function responses (Gemini 3+) */
+    supportsMultimodalFunctionResponse?: boolean;
     /** Whether the model supports PDF input */
     supportsPdf: boolean;
     /** Whether the model supports streaming responses */

package/dist/core/domain/cipher/process/types.d.ts

@@ -17,6 +17,13 @@ export interface ProcessConfig {
      * Custom environment variables for all commands.
      */
     environment: Record<string, string>;
+    /**
+     * Grace period in milliseconds to wait after SIGTERM before sending SIGKILL.
+     * Allows processes time to clean up gracefully.
+     *
+     * @default 5000 (5 seconds)
+     */
+    killGracePeriod: number;
     /**
      * Maximum number of concurrent background processes.
      * @default 5

package/dist/core/domain/cipher/session/session-metadata.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Session Metadata Types and Schemas
+ *
+ * Defines the data structures for persistent session management.
+ * Sessions are stored in .brv/sessions/ directory as JSON files.
+ *
+ * Design adapted from gemini-cli's ChatRecordingService pattern.
+ */
+import { z } from 'zod';
+/**
+ * Session status indicating lifecycle state.
+ */
+export type SessionStatus = 'active' | 'ended' | 'interrupted';
+/**
+ * Active session pointer stored in .brv/sessions/active.json
+ * Points to the currently active session for auto-resume.
+ */
+export interface ActiveSessionPointer {
+    /** ISO timestamp when this session became active */
+    activatedAt: string;
+    /** PID of the process that activated this session (for stale detection) */
+    pid: number;
+    /**
+     * Unique token identifying this specific process instance.
+     * Used to detect PID reuse: if the PID exists but token differs,
+     * it's a different process that got the same PID after the original crashed.
+     * Optional for backward compatibility with existing session files.
+     */
+    processToken?: string;
+    /** Session ID of the currently active session */
+    sessionId: string;
+}
+/**
+ * Session metadata stored in .brv/sessions/session-*.json
+ * Contains metadata about a session for listing and management.
+ */
+export interface SessionMetadata {
+    /** ISO timestamp when session was created */
+    createdAt: string;
+    /** ISO timestamp of last activity */
+    lastUpdated: string;
+    /** Number of messages in session (cached for quick display) */
+    messageCount: number;
+    /** Unique session identifier (UUID) */
+    sessionId: string;
+    /** Session lifecycle status */
+    status: SessionStatus;
+    /** Optional AI-generated summary */
+    summary?: string;
+    /** Session title (generated from first user message) */
+    title?: string;
+    /** Project working directory (for validation) */
+    workingDirectory: string;
+}
+/**
+ * Session info for display purposes (extends metadata with computed fields).
+ */
+export interface SessionInfo extends SessionMetadata {
+    /** Filename without extension */
+    file: string;
+    /** Full filename including .json extension */
+    fileName: string;
+    /** First user message content (cleaned) */
+    firstUserMessage?: string;
+    /** Display index in the list (1-based) */
+    index: number;
+    /** Whether this is the currently active session */
+    isCurrentSession: boolean;
+}
+/**
+ * Result of resolving a session selection.
+ */
+export interface SessionSelectionResult {
+    /** Display info string for user feedback */
+    displayInfo: string;
+    /** Loaded session metadata */
+    sessionData: SessionMetadata;
+    /** Full path to session metadata file */
+    sessionPath: string;
+}
+/**
+ * Schema for ActiveSessionPointer validation.
+ */
+export declare const ActiveSessionPointerSchema: z.ZodObject<{
+    activatedAt: z.ZodUnion<[z.ZodString, z.ZodString]>;
+    pid: z.ZodNumber;
+    processToken: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    pid: number;
+    activatedAt: string;
+    processToken?: string | undefined;
+}, {
+    sessionId: string;
+    pid: number;
+    activatedAt: string;
+    processToken?: string | undefined;
+}>;
+/**
+ * Schema for SessionMetadata validation.
+ */
+export declare const SessionMetadataSchema: z.ZodObject<{
+    createdAt: z.ZodUnion<[z.ZodString, z.ZodString]>;
+    lastUpdated: z.ZodUnion<[z.ZodString, z.ZodString]>;
+    messageCount: z.ZodNumber;
+    sessionId: z.ZodString;
+    status: z.ZodEnum<["active", "ended", "interrupted"]>;
+    summary: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    workingDirectory: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    status: "active" | "ended" | "interrupted";
+    sessionId: string;
+    createdAt: string;
+    lastUpdated: string;
+    messageCount: number;
+    workingDirectory: string;
+    summary?: string | undefined;
+    title?: string | undefined;
+}, {
+    status: "active" | "ended" | "interrupted";
+    sessionId: string;
+    createdAt: string;
+    lastUpdated: string;
+    messageCount: number;
+    workingDirectory: string;
+    summary?: string | undefined;
+    title?: string | undefined;
+}>;
+/** Prefix for session metadata files */
+export declare const SESSION_FILE_PREFIX = "session-";
+/** Directory name for session storage */
+export declare const SESSIONS_DIR = "sessions";
+/** Filename for active session pointer */
+export declare const ACTIVE_SESSION_FILE = "active.json";
+/** Default session retention config */
+export declare const DEFAULT_SESSION_RETENTION: {
+    /** Maximum age in days before auto-cleanup */
+    maxAgeDays: number;
+    /** Maximum number of sessions to keep */
+    maxCount: number;
+    /** Run cleanup on startup */
+    runOnStartup: boolean;
+};
+/**
+ * Generate a session filename from timestamp and session ID.
+ *
+ * @param sessionId - The session UUID
+ * @returns Filename in format: session-YYYY-MM-DDTHH-MM-SS-<uuid-prefix>.json
+ */
+export declare function generateSessionFilename(sessionId: string): string;
+/**
+ * Parse a session filename to extract timestamp and UUID prefix.
+ *
+ * @param filename - The session filename
+ * @returns Parsed components or null if invalid format
+ */
+export declare function parseSessionFilename(filename: string): null | {
+    timestamp: string;
+    uuidPrefix: string;
+};
+/**
+ * Format a timestamp as relative time.
+ *
+ * @param timestamp - ISO timestamp string
+ * @param style - 'long' (e.g., "2 hours ago") or 'short' (e.g., "2h")
+ * @returns Formatted relative time string
+ */
+export declare function formatRelativeTime(timestamp: string, style?: 'long' | 'short'): string;
+/**
+ * Clean and sanitize message content for display.
+ * Converts newlines to spaces, collapses whitespace, removes non-printable chars.
+ *
+ * @param message - Raw message content
+ * @returns Cleaned message suitable for display
+ */
+export declare function cleanMessageForTitle(message: string): string;