Sessions

export interface AppendResult {
    /** Messages that were trimmed from the session because maxMessages was exceeded. */
    overflow: ChatMessage[];
}

/**
 * Like `SessionManager` but writes each message as an individual entry instead
 * of re-serializing the whole conversation on every turn. Periodically rolls up
 * the loose entries into a snapshot to bound read latency.
 *
 * Storage layout (per sessionId):
 *
 *   ns="sessions:meta"       key=<sessionId>           -> Session minus messages
 *   ns="sessions:snapshot"   key=<sessionId>           -> { messages, nextSeq } (collapsed)
 *   ns="sessions:msg"        key=<sessionId>:<seq>     -> ChatMessage (incremental)
 *
 * `seq` is a zero-padded monotonically increasing integer so that
 * `list(ns, sessionId + ":")` returns entries in chronological order.
 */
export interface IncrementalSessionConfig {
    /** Take a full snapshot every N message appends. Default: 25. */
    snapshotFrequency?: number;
    /** Soft message limit applied to whole turns at snapshot time. Default: unlimited. */
    maxMessages?: number;
}

export declare class IncrementalSessionManager {
    constructor(storage: StorageDriver, config?: IncrementalSessionConfig);
    getOrCreate(sessionId: string, userId?: string): Promise<Session>;
    appendMessage(sessionId: string, msg: ChatMessage): Promise<void>;
    appendMessages(sessionId: string, msgs: ChatMessage[]): Promise<void>;
    /**
     * Force an immediate snapshot. Useful for graceful drains.
     */
    snapshotNow(sessionId: string): Promise<void>;
    getHistory(sessionId: string, limit?: number): Promise<ChatMessage[]>;
    updateState(sessionId: string, patch: Record<string, unknown>): Promise<void>;
    getState(sessionId: string): Promise<Record<string, unknown>>;
    deleteSession(sessionId: string): Promise<void>;
}

export interface Session {
    sessionId: string;
    userId?: string;
    messages: ChatMessage[];
    state: Record<string, unknown>;
    createdAt: Date;
    updatedAt: Date;
}

export declare class SessionManager {
    constructor(storage: StorageDriver, config?: SessionManagerConfig);
    getOrCreate(sessionId: string, userId?: string): Promise<Session>;
    appendMessage(sessionId: string, msg: ChatMessage): Promise<AppendResult>;
    appendMessages(sessionId: string, msgs: ChatMessage[]): Promise<AppendResult>;
    getHistory(sessionId: string, limit?: number): Promise<ChatMessage[]>;
    updateState(sessionId: string, patch: Record<string, unknown>): Promise<void>;
    getState(sessionId: string): Promise<Record<string, unknown>>;
    deleteSession(sessionId: string): Promise<void>;
    /** List stored sessions, optionally filtered by user. */
    listSessions(opts?: {
        userId?: string;
    }): Promise<Session[]>;
    /**
     * Search message text across sessions. Returns short snippets.
     * This is a simple substring search, not embeddings.
     */
    searchSessions(query: string, opts?: {
        userId?: string;
        limit?: number;
    }): Promise<Array<{
        sessionId: string;
        snippet: string;
    }>>;
}

export interface SessionManagerConfig {
    /** Soft message limit. Oldest whole turns are trimmed; the latest turn stays intact. Default: unlimited. */
    maxMessages?: number;
}