@luckydraw/cumulus 0.5.1

package/README.md

@@ -0,0 +1,148 @@
+# Cumulus
+
+A CLI chat wrapper for Claude that implements the **Recursive Language Model (RLM)** pattern for unlimited conversation context.
+
+## The Problem
+
+Standard LLM chat interfaces accumulate conversation history in the context window. As conversations grow:
+
+- **Context rot**: Model performance degrades as context fills up
+- **Compaction**: Old messages get summarized or dropped, losing detail
+- **Token limits**: Eventually you hit the wall, no matter how large the window
+
+## The Solution
+
+Cumulus treats conversation history as an **external environment** that Claude queries programmatically, rather than stuffing it all into context.
+
+```
+Traditional:  [msg1][msg2][msg3]...[msg847] → context rot, compaction, limits
+
+Cumulus:      [fresh context] + tools to query [external history]
+                     ↓
+              Claude retrieves what it needs, when it needs it
+```
+
+Each message is a **fresh Claude invocation**. Claude uses MCP tools to retrieve relevant context from the complete conversation history stored in local files.
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  $ cumulus my-project                                       │
+│  > Help me refactor the auth module we discussed yesterday  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                         Cumulus                              │
+│  1. Append user message to history                          │
+│  2. Spawn fresh: claude --print --mcp-config history.json   │
+│  3. Claude uses search_history("auth module") tool          │
+│  4. Claude retrieves relevant messages from history         │
+│  5. Claude responds with full context awareness             │
+│  6. Append response to history                              │
+│  7. Next message: completely fresh context                  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  ~/.cumulus/threads/my-project.jsonl                        │
+│  ────────────────────────────────────────                   │
+│  Full conversation history, never truncated                 │
+│  Claude queries via MCP tools as needed                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Key Features
+
+- **Unlimited history**: Conversations can span thousands of messages without degradation
+- **Full Claude Code power**: All tools work (Bash, Edit, Read, etc.) - cumulus just manages context
+- **Persistent threads**: Pick up any conversation where you left off
+- **Selective retrieval**: Claude decides what context it needs, reducing noise
+- **Cost efficient**: Only retrieve relevant context, not everything
+
+## Installation
+
+```bash
+npm install -g cumulus-cli
+```
+
+## Usage
+
+```bash
+# Start or continue a conversation thread
+cumulus my-project
+
+# List all threads
+cumulus --list
+
+# Delete a thread
+cumulus --delete old-project
+```
+
+## MCP Tools Available to Claude
+
+When you chat through Cumulus, Claude has access to:
+
+| Tool                | Description                                          |
+| ------------------- | ---------------------------------------------------- |
+| `search_history`    | Find messages by keyword, semantic, or hybrid search |
+| `read_messages`     | Read a specific range of messages                    |
+| `peek_recent`       | See the last few messages                            |
+| `get_history_stats` | Get count and token estimate                         |
+| `sub_query`         | Ask focused questions about history snippets         |
+| `get_summary`       | Get auto-generated summaries of conversation history |
+
+## Architecture
+
+```
+src/
+├── lib/
+│   └── history.ts      # JSONL storage for conversation history
+├── mcp/
+│   ├── server.ts       # MCP server exposing history tools
+│   └── index.ts        # MCP entry point
+└── cli/
+    └── cumulus.ts      # Main CLI, chat loop, Claude invocation
+```
+
+## Background
+
+This project implements ideas from the paper ["Recursive Language Models"](https://arxiv.org/abs/...) which demonstrates that treating long prompts as external environment objects—rather than feeding them directly into the context window—dramatically improves performance on long-context tasks while maintaining reasonable costs.
+
+Key insight: LLMs can programmatically examine, decompose, and query their context rather than processing it all at once. This enables effective reasoning over contexts 2+ orders of magnitude beyond the model's context window.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Lint
+npm run lint
+```
+
+## Roadmap
+
+**Phase 1 (MVP)**
+
+- [x] Project setup with TypeScript/ESLint
+- [x] HistoryStore for JSONL persistence
+- [x] MCP server with history tools
+- [x] CLI wrapper with pure RLM chat loop
+- [x] Basic test suite
+
+**Phase 2 (Enhancements)**
+
+- [x] Semantic search with embeddings
+- [x] Periodic summarization for very long histories
+
+## License
+
+MIT

package/dist/cli/cumulus.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cumulus.d.ts.map

package/dist/cli/cumulus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cumulus.d.ts","sourceRoot":"","sources":["../../src/cli/cumulus.ts"],"names":[],"mappings":""}

package/dist/cli/cumulus.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+import * as fs from 'fs';
+import { createRequire } from 'module';
+import * as os from 'os';
+import * as path from 'path';
+import * as readline from 'readline';
+import { Command } from 'commander';
+const require = createRequire(import.meta.url);
+const { version: pkgVersion } = require('../../package.json');
+import { addAlwaysIncludeFile, removeAlwaysIncludeFile, listAlwaysIncludeFiles, resolveFilePath, } from '../lib/config.js';
+import { HistoryStore } from '../lib/history.js';
+import { migrateThread, needsMigration } from '../lib/migrate.js';
+import { startTui } from '../tui/index.js';
+const CUMULUS_DIR = path.join(os.homedir(), '.cumulus');
+const THREADS_DIR = path.join(CUMULUS_DIR, 'threads');
+function ensureDirectories() {
+    if (!fs.existsSync(THREADS_DIR)) {
+        fs.mkdirSync(THREADS_DIR, { recursive: true });
+    }
+}
+function getThreadPath(threadName) {
+    return path.join(THREADS_DIR, `${threadName}.jsonl`);
+}
+function validateThreadName(name) {
+    return /^[a-zA-Z0-9_-]+$/.test(name);
+}
+function startChatLoop(threadName, debugMode) {
+    ensureDirectories();
+    if (!validateThreadName(threadName)) {
+        console.error('Invalid thread name. Use only letters, numbers, hyphens, and underscores.');
+        process.exit(1);
+    }
+    // Launch the TUI
+    startTui({ threadName, debugMode });
+}
+async function listThreads() {
+    ensureDirectories();
+    const files = fs.readdirSync(THREADS_DIR).filter(f => f.endsWith('.jsonl'));
+    if (files.length === 0) {
+        console.log('No threads found.');
+        return;
+    }
+    console.log('\nThreads:\n');
+    for (const file of files) {
+        const threadName = file.replace('.jsonl', '');
+        const threadPath = path.join(THREADS_DIR, file);
+        const fileStat = fs.statSync(threadPath);
+        const store = new HistoryStore(threadPath);
+        const stats = await store.getStats();
+        const lastModified = fileStat.mtime.toLocaleDateString();
+        console.log(`  ${threadName}`);
+        console.log(`    Messages: ${stats.count}`);
+        console.log(`    Tokens: ~${stats.totalTokens}`);
+        console.log(`    Last active: ${lastModified}`);
+        console.log();
+    }
+}
+async function deleteThread(threadName) {
+    const threadPath = getThreadPath(threadName);
+    if (!fs.existsSync(threadPath)) {
+        console.log(`Thread "${threadName}" not found.`);
+        return;
+    }
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise(resolve => {
+        rl.question(`Delete thread "${threadName}"? (y/N) `, answer => {
+            rl.close();
+            if (answer.toLowerCase() === 'y') {
+                fs.unlinkSync(threadPath);
+                console.log(`Thread "${threadName}" deleted.`);
+            }
+            else {
+                console.log('Cancelled.');
+            }
+            resolve();
+        });
+    });
+}
+async function configList(threadName) {
+    const files = await listAlwaysIncludeFiles(threadName);
+    console.log('\nAlways-Include Files Configuration\n');
+    if (files.global.length > 0) {
+        console.log('Global (~/.cumulus/config.json):');
+        for (const file of files.global) {
+            const resolved = resolveFilePath(file, process.cwd());
+            console.log(`  ${file}`);
+            if (resolved !== file) {
+                console.log(`    -> ${resolved}`);
+            }
+        }
+        console.log();
+    }
+    else {
+        console.log('Global: (none)\n');
+    }
+    if (threadName) {
+        if (files.thread.length > 0) {
+            console.log(`Thread "${threadName}":`);
+            for (const file of files.thread) {
+                const resolved = resolveFilePath(file, process.cwd());
+                console.log(`  ${file}`);
+                if (resolved !== file) {
+                    console.log(`    -> ${resolved}`);
+                }
+            }
+            console.log();
+        }
+        else {
+            console.log(`Thread "${threadName}": (none)\n`);
+        }
+        if (files.merged.length > 0) {
+            console.log('Effective (merged):');
+            for (const file of files.merged) {
+                console.log(`  ${file}`);
+            }
+            console.log();
+        }
+    }
+}
+async function configAdd(filePath, threadName) {
+    await addAlwaysIncludeFile(filePath, threadName);
+    const scope = threadName ? `thread "${threadName}"` : 'global';
+    console.log(`Added "${filePath}" to ${scope} always-include files.`);
+}
+async function configRemove(filePath, threadName) {
+    await removeAlwaysIncludeFile(filePath, threadName);
+    const scope = threadName ? `thread "${threadName}"` : 'global';
+    console.log(`Removed "${filePath}" from ${scope} always-include files.`);
+}
+async function migrate(threadName, options) {
+    const threadPath = getThreadPath(threadName);
+    if (!fs.existsSync(threadPath)) {
+        console.error(`Thread "${threadName}" not found.`);
+        process.exit(1);
+    }
+    if (options.check) {
+        // Just check status
+        const status = await needsMigration(threadPath);
+        console.log(`\nThread: ${threadName}`);
+        console.log(`  Messages: ${status.messageCount}`);
+        console.log(`  Embeddings: ${status.embeddingCount}/${status.messageCount}`);
+        console.log(`  Needs embeddings: ${status.needsEmbeddings ? 'yes' : 'no'}`);
+        console.log(`  Needs sessions: ${status.needsSessions ? 'yes' : 'no'}`);
+        if (!status.needsEmbeddings && !status.needsSessions) {
+            console.log('\n  Thread is fully migrated.');
+        }
+        else {
+            console.log('\n  Run `cumulus migrate ' + threadName + '` to migrate.');
+        }
+        return;
+    }
+    console.log(`\nMigrating thread: ${threadName}\n`);
+    const result = await migrateThread(threadPath, progress => {
+        const phases = {
+            loading: '[1/3]',
+            embeddings: '[2/3]',
+            sessions: '[3/3]',
+            done: '[done]',
+        };
+        const prefix = phases[progress.phase] || '';
+        process.stdout.write(`\r${prefix} ${progress.message}`.padEnd(60));
+    });
+    console.log('\n');
+    console.log('Migration complete:');
+    console.log(`  Messages: ${result.messagesTotal}`);
+    console.log(`  Embeddings generated: ${result.embeddingsGenerated}`);
+    console.log(`  Session: ${result.sessionCreated ? `created with ${result.sessionExchanges} exchanges` : 'skipped (already exists)'}`);
+    if (result.errors.length > 0) {
+        console.log('\nErrors:');
+        for (const error of result.errors) {
+            console.log(`  - ${error}`);
+        }
+    }
+}
+// Main program
+const program = new Command();
+program
+    .name('cumulus')
+    .description('RLM-based CLI chat wrapper for Claude with external history context')
+    .version(pkgVersion)
+    .argument('[thread]', 'Thread name to start or continue', 'default')
+    .option('-l, --list', 'List all threads')
+    .option('-d, --delete <name>', 'Delete a thread')
+    .option('--debug', 'Show context being sent to Claude with color-coded provenance')
+    .action(async (thread, options) => {
+    if (options.list) {
+        await listThreads();
+    }
+    else if (options.delete) {
+        await deleteThread(options.delete);
+    }
+    else {
+        startChatLoop(thread, options.debug ?? false);
+    }
+});
+// Config subcommand
+const configCommand = program
+    .command('config')
+    .description('Manage always-include files configuration');
+configCommand
+    .command('list')
+    .description('List always-include files')
+    .option('-t, --thread <name>', 'Show thread-specific config')
+    .action(async (options) => {
+    await configList(options.thread);
+});
+configCommand
+    .command('add <file>')
+    .description('Add a file to always-include list')
+    .option('-t, --thread <name>', 'Add to thread-specific config instead of global')
+    .action(async (file, options) => {
+    await configAdd(file, options.thread);
+});
+configCommand
+    .command('remove <file>')
+    .description('Remove a file from always-include list')
+    .option('-t, --thread <name>', 'Remove from thread-specific config instead of global')
+    .action(async (file, options) => {
+    await configRemove(file, options.thread);
+});
+// Migrate subcommand
+program
+    .command('migrate <thread>')
+    .description('Migrate an old thread to support RAG features (embeddings + sessions)')
+    .option('-c, --check', 'Check migration status without migrating')
+    .action(async (thread, options) => {
+    await migrate(thread, options);
+});
+program.parse();
+//# sourceMappingURL=cumulus.js.map

package/dist/cli/cumulus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cumulus.js","sourceRoot":"","sources":["../../src/cli/cumulus.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+export { HistoryStore } from './lib/history.js';
+export type { Attachment, Message, HistoryStats } from './lib/history.js';
+export { ContentStore } from './lib/content-store.js';
+export type { ContentType, ContentSourceType, ContentChunk, StoredContentMeta, StoredContent, StoreOptions, SearchOptions, ContentSearchResult, } from './lib/content-store.js';
+export { analyzeContent, generateHeuristicSummary, generateLLMSummary, generateSummary, detectContentType, } from './lib/content-detector.js';
+export type { ContentAnalysis, SummaryOptions } from './lib/content-detector.js';
+export { estimateTokens, ContextBudget } from './lib/context-budget.js';
+export type { ContextBudgetConfig } from './lib/context-budget.js';
+export { cosineSimilarity, embeddingsAvailable, generateMissingEmbeddings, getEmbeddingProvider, getEmbeddingsPath, loadEmbeddings, saveEmbeddings, } from './lib/embeddings.js';
+export type { EmbeddingConfig, EmbeddingEntry, EmbeddingProvider, EmbeddingsFile, } from './lib/embeddings.js';
+export { SessionManager } from './lib/session.js';
+export type { SessionChunk, SessionSearchResult } from './lib/session.js';
+export { retrieve, RETRIEVAL_BUDGET_FRACTION } from './lib/retriever.js';
+export type { RetrievalResult, RetrieverOptions } from './lib/retriever.js';
+export { StreamProcessor, shouldExternalizeUserInput, externalizeUserInput, } from './lib/stream-processor.js';
+export type { StreamEventType, StreamMessage, ProcessedLine, StreamProcessorConfig, } from './lib/stream-processor.js';
+export { loadGlobalConfig, loadThreadConfig, mergeConfigs, resolveFilePath, readAlwaysIncludeFiles, saveConfig, addAlwaysIncludeFile, removeAlwaysIncludeFile, listAlwaysIncludeFiles, } from './lib/config.js';
+export type { CumulusConfig, AlwaysIncludeFile, AlwaysIncludeResult } from './lib/config.js';
+export { processImagesInMessage, readClipboardImage } from './lib/image-utils.js';
+export type { DetectedImage, ImageProcessingResult } from './lib/image-utils.js';
+export { isGitRepo, captureSnapshot, restoreSnapshot } from './lib/snapshots.js';
+export type { GitSnapshot, RestoreResult } from './lib/snapshots.js';
+export { getSummary, getSummaryPath, loadSummaries, runSummarization, saveSummaries, shouldSummarize, generateChunkSummary, generateSessionSummary, } from './lib/summarizer.js';
+export type { GetSummaryResult, Summary, SummaryFile } from './lib/summarizer.js';
+export { executeRevert } from './lib/revert.js';
+export type { RevertResult, RevertOptions } from './lib/revert.js';
+export { startSharedMcpServer } from './mcp/shared-server.js';
+export type { SharedMcpServerOptions, SharedMcpServerHandle } from './mcp/shared-server.js';
+/** Absolute path to the lightweight stdio→HTTP proxy script for shared MCP server */
+export declare function getProxyPath(): string;
+/** Absolute path to the standalone MCP stdio server (full, non-shared) */
+export declare function getMcpServerPath(): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAG1E,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,YAAY,EACV,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,GAClB,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGjF,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxE,YAAY,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAGnE,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,EACzB,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,EACd,cAAc,GACf,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,cAAc,GACf,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAG1E,OAAO,EAAE,QAAQ,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AACzE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG5E,OAAO,EACL,eAAe,EACf,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,2BAA2B,CAAC;AACnC,YAAY,EACV,eAAe,EACf,aAAa,EACb,aAAa,EACb,qBAAqB,GACtB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,sBAAsB,EACtB,UAAU,EACV,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAG7F,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAClF,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAGjF,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACjF,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGrE,OAAO,EACL,UAAU,EACV,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGlF,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAQ5F,qFAAqF;AACrF,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC"}

package/dist/index.js

@@ -0,0 +1,43 @@
+// Cumulus - RLM-based CLI chat wrapper for Claude
+// Exports for library usage
+// History
+export { HistoryStore } from './lib/history.js';
+// Content Store
+export { ContentStore } from './lib/content-store.js';
+// Content Detector
+export { analyzeContent, generateHeuristicSummary, generateLLMSummary, generateSummary, detectContentType, } from './lib/content-detector.js';
+// Context Budget
+export { estimateTokens, ContextBudget } from './lib/context-budget.js';
+// Embeddings
+export { cosineSimilarity, embeddingsAvailable, generateMissingEmbeddings, getEmbeddingProvider, getEmbeddingsPath, loadEmbeddings, saveEmbeddings, } from './lib/embeddings.js';
+// Session
+export { SessionManager } from './lib/session.js';
+// Retriever
+export { retrieve, RETRIEVAL_BUDGET_FRACTION } from './lib/retriever.js';
+// Stream Processor
+export { StreamProcessor, shouldExternalizeUserInput, externalizeUserInput, } from './lib/stream-processor.js';
+// Config
+export { loadGlobalConfig, loadThreadConfig, mergeConfigs, resolveFilePath, readAlwaysIncludeFiles, saveConfig, addAlwaysIncludeFile, removeAlwaysIncludeFile, listAlwaysIncludeFiles, } from './lib/config.js';
+// Image Utils
+export { processImagesInMessage, readClipboardImage } from './lib/image-utils.js';
+// Snapshots
+export { isGitRepo, captureSnapshot, restoreSnapshot } from './lib/snapshots.js';
+// Summarizer
+export { getSummary, getSummaryPath, loadSummaries, runSummarization, saveSummaries, shouldSummarize, generateChunkSummary, generateSessionSummary, } from './lib/summarizer.js';
+// Revert
+export { executeRevert } from './lib/revert.js';
+// MCP - Shared server for multi-agent setups
+export { startSharedMcpServer } from './mcp/shared-server.js';
+// MCP paths - for spawning subprocesses via --mcp-config
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+const __mcp_dirname = dirname(fileURLToPath(import.meta.url));
+/** Absolute path to the lightweight stdio→HTTP proxy script for shared MCP server */
+export function getProxyPath() {
+    return join(__mcp_dirname, 'mcp', 'proxy.js');
+}
+/** Absolute path to the standalone MCP stdio server (full, non-shared) */
+export function getMcpServerPath() {
+    return join(__mcp_dirname, 'mcp', 'index.js');
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,4BAA4B;AAE5B,UAAU;AACV,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGhD,gBAAgB;AAChB,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAYtD,mBAAmB;AACnB,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,GAClB,MAAM,2BAA2B,CAAC;AAGnC,iBAAiB;AACjB,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAGxE,aAAa;AACb,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,EACzB,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,EACd,cAAc,GACf,MAAM,qBAAqB,CAAC;AAQ7B,UAAU;AACV,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD,YAAY;AACZ,OAAO,EAAE,QAAQ,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAGzE,mBAAmB;AACnB,OAAO,EACL,eAAe,EACf,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,2BAA2B,CAAC;AAQnC,SAAS;AACT,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,sBAAsB,EACtB,UAAU,EACV,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AAGzB,cAAc;AACd,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAGlF,YAAY;AACZ,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGjF,aAAa;AACb,OAAO,EACL,UAAU,EACV,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAG7B,SAAS;AACT,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhD,6CAA6C;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAG9D,yDAAyD;AACzD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE9D,qFAAqF;AACrF,MAAM,UAAU,YAAY;IAC1B,OAAO,IAAI,CAAC,aAAa,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;AAChD,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,gBAAgB;IAC9B,OAAO,IAAI,CAAC,aAAa,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;AAChD,CAAC"}

package/dist/lib/config.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Configuration loading and always-include file management.
+ *
+ * Handles global and per-thread configuration, including reading
+ * files that should always be included in the context window.
+ */
+/** Configuration structure for Cumulus */
+export interface CumulusConfig {
+    /** File paths to always include in context */
+    alwaysInclude?: string[];
+    /** Project directory for this thread (used by callers like Janus to set cwd) */
+    projectDir?: string;
+}
+/** Information about a single always-include file */
+export interface AlwaysIncludeFile {
+    /** Original path from config */
+    path: string;
+    /** Absolute resolved path */
+    resolvedPath: string;
+    /** File contents (may be truncated) */
+    content: string;
+    /** Token count of content */
+    tokens: number;
+    /** Whether content was truncated */
+    truncated: boolean;
+    /** Error message if file couldn't be read */
+    error?: string;
+}
+/** Result of reading all always-include files */
+export interface AlwaysIncludeResult {
+    /** Information about each file */
+    files: AlwaysIncludeFile[];
+    /** Total tokens across all files */
+    totalTokens: number;
+    /** Formatted context string for system prompt */
+    formattedContext: string;
+}
+/**
+ * Load the global configuration from ~/.cumulus/config.json
+ */
+export declare function loadGlobalConfig(): Promise<CumulusConfig>;
+/**
+ * Load thread-specific configuration from ~/.cumulus/threads/{thread}.config.json
+ */
+export declare function loadThreadConfig(threadName: string): Promise<CumulusConfig>;
+/**
+ * Merge global and thread configs. Thread config adds to global (doesn't override).
+ */
+export declare function mergeConfigs(global: CumulusConfig, thread: CumulusConfig): CumulusConfig;
+/**
+ * Resolve a file path that may use ~ or be relative.
+ * @param filePath - The path from config (may use ~, be relative, or absolute)
+ * @param cwd - Current working directory for relative paths
+ */
+export declare function resolveFilePath(filePath: string, cwd: string): string;
+/**
+ * Read and format all always-include files from config.
+ * @param config - Merged configuration
+ * @param cwd - Current working directory for relative paths
+ */
+export declare function readAlwaysIncludeFiles(config: CumulusConfig, cwd: string): Promise<AlwaysIncludeResult>;
+/**
+ * Save configuration to a file.
+ */
+export declare function saveConfig(config: CumulusConfig, threadName?: string): Promise<void>;
+/**
+ * Add a file to the always-include list.
+ * @param filePath - Path to add
+ * @param threadName - Thread name for thread-specific config, undefined for global
+ */
+export declare function addAlwaysIncludeFile(filePath: string, threadName?: string): Promise<void>;
+/**
+ * Remove a file from the always-include list.
+ * @param filePath - Path to remove
+ * @param threadName - Thread name for thread-specific config, undefined for global
+ */
+export declare function removeAlwaysIncludeFile(filePath: string, threadName?: string): Promise<void>;
+/**
+ * List all always-include files from config (without reading them).
+ */
+export declare function listAlwaysIncludeFiles(threadName?: string): Promise<{
+    global: string[];
+    thread: string[];
+    merged: string[];
+}>;
+//# sourceMappingURL=config.d.ts.map

package/dist/lib/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,SAAS,EAAE,OAAO,CAAC;IACnB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,iDAAiD;AACjD,MAAM,WAAW,mBAAmB;IAClC,kCAAkC;IAClC,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,aAAa,CAAC,CAG/D;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAGjF;AAkDD;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,GAAG,aAAa,CA0BxF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAgBrE;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,aAAa,EACrB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,mBAAmB,CAAC,CAiD9B;AAyBD;;GAEG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,aAAa,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAY1F;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU/F;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACzE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC,CAUD"}