dual-brain 0.2.30 → 0.3.0

package/dist/src/session.d.ts

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+/**
+ * session.ts — Persist task state between terminal sessions.
+ *
+ * Exports:
+ *   loadSession(cwd)                      → session state or null (if stale/missing)
+ *   saveSession(state, cwd)               → write session atomically
+ *   updateSession(patch, cwd)             → merge partial update into existing session
+ *   clearSession(cwd)                     → delete session file
+ *   formatSessionCard(session, repo, health) → compact status card string (≤5 lines)
+ */
+export type SessionPhase = 'idle' | 'active' | 'paused' | 'complete' | 'failed';
+export interface SessionState {
+    startedAt: string;
+    updatedAt: string;
+    objective: string | null;
+    branch: string | null;
+    filesChanged: string[];
+    commandsRun: string[];
+    lastResult: SessionResult | null;
+    provider: string | null;
+    nextAction: string | null;
+}
+export interface SessionResult {
+    status?: 'success' | 'failure' | 'partial';
+    summary?: string;
+}
+export interface SessionPatch {
+    startedAt?: string;
+    updatedAt?: string;
+    objective?: string | null;
+    branch?: string | null;
+    filesChanged?: string[];
+    commandsRun?: string[];
+    lastResult?: SessionResult | null;
+    provider?: string | null;
+    nextAction?: string | null;
+}
+export interface RepoInfo {
+    name?: string;
+    type?: string;
+    packageManager?: string;
+    branch?: string;
+    dirty?: boolean;
+    commands?: {
+        test?: string;
+    };
+}
+export interface HealthInfo {
+    states?: Record<string, {
+        status?: string;
+    }>;
+    session?: unknown;
+}
+export interface ProfileInfo {
+    providers?: Record<string, {
+        enabled?: boolean;
+    }>;
+}
+export interface ReplitSession {
+    id: string;
+    name: string;
+    smartName?: string | null;
+    project: string;
+    promptCount: number;
+    lastActive: string;
+    isActive: boolean;
+    source: string;
+    age: string;
+    tool?: string;
+}
+export interface SessionMeta {
+    [sessionId: string]: {
+        name?: string;
+        pinned?: boolean;
+        category?: string | null;
+        createdAt?: string;
+    };
+}
+export interface ArchivedSession {
+    id: string;
+    archived: boolean;
+    archivedAt: string;
+    [key: string]: unknown;
+}
+export interface EnrichedSession extends ReplitSession {
+    pinned: boolean;
+    category: string | null;
+}
+export interface SessionIndexEntry {
+    id: string;
+    topics: string[];
+    files: string[];
+    prompts: {
+        first: string;
+        last: string;
+    };
+    date: string | null;
+    messageCount: number;
+    tool: string;
+    smartName?: string;
+    archived?: boolean;
+    _fileSize: number;
+}
+export interface SessionSearchResult {
+    sessionId: string;
+    date: string | null;
+    relevance: number;
+    _score: number;
+    files: string[];
+    summary: string;
+    matchingLines: string[];
+    messageCount: number;
+}
+export interface RelatedSession {
+    sessionId: string;
+    smartName: string;
+    score: number;
+    matchedFiles: string[];
+    matchedTopics: string[];
+    date: string | null;
+    messageCount: number;
+}
+export interface SessionContext {
+    lastPrompt: string | null;
+    filesTouched: string[];
+    totalLines: number;
+}
+export interface ExtractedSessionMeta {
+    id: string;
+    date: string | null;
+    messageCount: number;
+    files: string[];
+    taskSummary: string | null;
+    firstPrompt: string | null;
+    lastPrompt: string | null;
+    duration: number | null;
+}
+export interface RoutingContext {
+    relatedSessions: Array<{
+        sessionId: string;
+        date: string | null;
+        taskSummary: string | null;
+        score: number;
+        messageCount: number;
+        files: string[];
+    }>;
+    riskSignals: string[];
+    priorAttempts: Array<{
+        sessionId: string;
+        date: string | null;
+        summary: string | null;
+        likelyIncomplete: boolean;
+    }>;
+    relevantFiles: string[];
+}
+/**
+ * Load the session file. Returns null if missing or older than 24 hours.
+ */
+export declare function loadSession(cwd?: string): SessionState | null;
+/**
+ * Write session state atomically (tmp + rename).
+ */
+export declare function saveSession(state: SessionPatch, cwd?: string): SessionState;
+/**
+ * Merge a partial update into the existing session (or create a new one).
+ */
+export declare function updateSession(patch: SessionPatch, cwd?: string): SessionState;
+/**
+ * Delete the session file.
+ */
+export declare function clearSession(cwd?: string): void;
+/**
+ * Format a compact status card (≤5 lines) for display when running `dual-brain`.
+ */
+export declare function formatSessionCard(session: SessionState | null, repo: RepoInfo, health: HealthInfo | null, profile?: ProfileInfo): string;
+/**
+ * Import sessions from replit-tools history.jsonl.
+ * Returns an array of session summary objects, sorted most-recent first.
+ * Returns [] gracefully if replit-tools is not present.
+ */
+export declare function importReplitSessions(cwd?: string): ReplitSession[];
+export declare function getSessionMeta(cwd?: string): SessionMeta;
+export declare function saveSessionMeta(meta: SessionMeta, cwd?: string): void;
+/**
+ * Archive a session — moves it from active sessions.json to archive/sessions.json.
+ * The session data stays in the index (searchable), just flagged as archived.
+ * Non-destructive and reversible.
+ */
+export declare function archiveSession(sessionId: string, cwd?: string): void;
+/**
+ * Return all archived sessions.
+ */
+export declare function getArchivedSessions(cwd?: string): ArchivedSession[];
+export declare function renameSession(sessionId: string, name: string, cwd?: string): void;
+export declare function pinSession(sessionId: string, cwd?: string): void;
+export declare function unpinSession(sessionId: string, cwd?: string): void;
+export declare function categorizeSession(sessionId: string, category: string, cwd?: string): void;
+export declare function autoLabel(session: {
+    name?: string;
+}): string | null;
+export declare function enrichSessions(sessions: ReplitSession[], cwd?: string): EnrichedSession[];
+/**
+ * Ensure Claude and Codex are configured to retain session history indefinitely.
+ * Mirrors what replit-tools does to prevent session cleanup/deletion.
+ */
+export declare function ensurePersistence(cwd?: string): string[];
+/**
+ * Append-only mirror sync for Claude/Codex sessions (matches what replit-tools does).
+ * Files in the mirror only grow — if the source deletes a session, the mirror still has it.
+ */
+export declare function syncSessionMirror(cwd?: string): {
+    copied: number;
+    grew: number;
+    disabled?: boolean;
+};
+/**
+ * Generate a smart human-readable session name from session index data.
+ *
+ * Priority:
+ *   1. Dominant file pattern (e.g. auth*.mjs -> "Refactor Auth Module")
+ *   2. Top topics (e.g. ['auth','token','refresh'] -> "Auth Token Refresh")
+ *   3. Fallback: first prompt truncated to 40 chars
+ *
+ * Rules: <=40 chars, Title Case, no file extensions, action-prefixed when detectable.
+ */
+export declare function generateSmartName(sessionData: {
+    topics?: string[];
+    files?: string[];
+    prompts?: {
+        first?: string;
+    };
+}): string;
+/**
+ * Build/update `.dualbrain/session-index.json` from Claude and Codex JSONL session files.
+ * Extracts topics, file references, prompt snippets, and metadata per session.
+ */
+export declare function buildSessionIndex(cwd?: string): Record<string, SessionIndexEntry>;
+/**
+ * Search sessions using the replit-tools archive as primary source.
+ * Falls back to the parallel session index when archive is unavailable.
+ *
+ * Results include: { sessionId, date, relevance, files, summary, matchingLines }
+ * Sorted by relevance * recencyMultiplier descending.
+ */
+export declare function searchSessions(query: string, cwd?: string): SessionSearchResult[];
+/**
+ * Find sessions related to a new task prompt and file list.
+ * Uses the session index (topics + files) — does not parse full JSONL files.
+ */
+export declare function findRelatedSessions(prompt: string, files?: string[], cwd?: string): RelatedSession[];
+/**
+ * Get detailed context for a session (for smart resume preview).
+ * Reads the last 20 lines of the session JSONL to surface the most recent prompt
+ * and files touched.
+ */
+export declare function getSessionContext(sessionId: string, cwd?: string): SessionContext | null;
+/**
+ * Extract structured metadata from a session JSONL file.
+ * Reads the file once; handles malformed entries gracefully.
+ */
+export declare function extractSessionMeta(sessionFilePath: string): ExtractedSessionMeta;
+/**
+ * Build routing context from recent sessions (last 7 days) related to a task.
+ * Used by the dispatch pipeline to detect prior attempts and flag risk signals.
+ */
+export declare function getRoutingContext(cwd: string, taskDescription: string): RoutingContext;