contextos-mcp 0.4.0

package/dist/threads/cache.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Thread cache — caches thread results by (task, files, agent) hash.
+ *
+ * Slate's "subthread reuse" optimization: when the orchestrator spawns
+ * an identical thread (same task + same files + same agent), return the
+ * cached result instead of re-running the agent. Saves cost and time.
+ *
+ * Two modes:
+ *   1. Session-scoped (default): in-memory Map, cleared on exit.
+ *   2. Disk-persistent: reads/writes JSON files in a cache directory,
+ *      with TTL-based expiry so stale entries don't accumulate.
+ *
+ * Cache keys are SHA-256 hashes of normalized (task, files, agent, model).
+ */
+import type { CompressedResult } from "../core/types.js";
+export interface ThreadCacheEntry {
+    result: CompressedResult;
+    cachedAt: number;
+    hitCount: number;
+    fileHashes?: Record<string, string>;
+    commitSha?: string;
+}
+/** Compute SHA-256 hash of a file on disk. Returns empty string if file does not exist. */
+export declare function computeFileHash(filePath: string): string;
+/** Compute file hashes for a list of context files inside repoRoot. */
+export declare function computeContextHashes(repoRoot: string, files: string[]): Record<string, string>;
+export interface ThreadCacheStats {
+    size: number;
+    hits: number;
+    misses: number;
+    totalSavedMs: number;
+    totalSavedUsd: number;
+    persistedEntries: number;
+}
+export declare class ThreadCache {
+    private cache;
+    private hits;
+    private misses;
+    private totalSavedMs;
+    private totalSavedUsd;
+    private maxEntries;
+    private persistDir?;
+    private ttlMs;
+    private persistedKeys;
+    constructor(maxEntries?: number, persistDir?: string, ttlHours?: number);
+    /** Initialize persistent cache — load entries from disk. */
+    init(): Promise<void>;
+    /**
+     * Look up a cached result for the given thread parameters.
+     * Returns undefined on cache miss or if context files drifted.
+     */
+    get(task: string, files: string[], agent: string, model: string, repoRoot?: string, commitSha?: string): CompressedResult | undefined;
+    /**
+     * Store a thread result in the cache.
+     * Only caches successful results — failed threads should be retried.
+     */
+    set(task: string, files: string[], agent: string, model: string, result: CompressedResult, repoRoot?: string, commitSha?: string): void;
+    /** Get cache statistics. */
+    getStats(): ThreadCacheStats;
+    /** Clear all cached entries (in-memory and on disk). */
+    clear(): void;
+    private saveDiskEntry;
+    private deleteDiskEntry;
+}

package/dist/threads/cache.js

@@ -0,0 +1,241 @@
+/**
+ * Thread cache — caches thread results by (task, files, agent) hash.
+ *
+ * Slate's "subthread reuse" optimization: when the orchestrator spawns
+ * an identical thread (same task + same files + same agent), return the
+ * cached result instead of re-running the agent. Saves cost and time.
+ *
+ * Two modes:
+ *   1. Session-scoped (default): in-memory Map, cleared on exit.
+ *   2. Disk-persistent: reads/writes JSON files in a cache directory,
+ *      with TTL-based expiry so stale entries don't accumulate.
+ *
+ * Cache keys are SHA-256 hashes of normalized (task, files, agent, model).
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** Compute SHA-256 hash of a file on disk. Returns empty string if file does not exist. */
+export function computeFileHash(filePath) {
+    try {
+        if (!fs.existsSync(filePath))
+            return "";
+        const buffer = fs.readFileSync(filePath);
+        return createHash("sha256").update(buffer).digest("hex");
+    }
+    catch {
+        return "";
+    }
+}
+/** Compute file hashes for a list of context files inside repoRoot. */
+export function computeContextHashes(repoRoot, files) {
+    const hashes = {};
+    for (const file of files) {
+        const absPath = path.isAbsolute(file) ? file : path.join(repoRoot, file);
+        hashes[file] = computeFileHash(absPath);
+    }
+    return hashes;
+}
+/**
+ * Compute a stable cache key from thread parameters.
+ * Normalizes inputs: trims task, sorts files, lowercases agent/model.
+ */
+function computeCacheKey(task, files, agent, model, repoRoot = "", commitSha = "") {
+    const normalized = JSON.stringify({
+        task: task.trim(),
+        files: [...files].sort(),
+        agent: agent.toLowerCase(),
+        model: model.toLowerCase(),
+        repo: repoRoot.trim().toLowerCase(),
+        commit: commitSha.trim(),
+    });
+    return createHash("sha256").update(normalized).digest("hex");
+}
+export class ThreadCache {
+    cache = new Map();
+    hits = 0;
+    misses = 0;
+    totalSavedMs = 0;
+    totalSavedUsd = 0;
+    maxEntries;
+    persistDir;
+    ttlMs;
+    persistedKeys = new Set();
+    constructor(maxEntries = 100, persistDir, ttlHours = 24) {
+        this.maxEntries = maxEntries;
+        this.persistDir = persistDir;
+        this.ttlMs = ttlHours * 60 * 60 * 1000;
+    }
+    /** Initialize persistent cache — load entries from disk. */
+    async init() {
+        if (!this.persistDir)
+            return;
+        fs.mkdirSync(this.persistDir, { recursive: true });
+        let files;
+        try {
+            files = fs.readdirSync(this.persistDir).filter((f) => f.endsWith(".json"));
+        }
+        catch {
+            return;
+        }
+        const now = Date.now();
+        for (const file of files) {
+            try {
+                const filePath = path.join(this.persistDir, file);
+                const raw = fs.readFileSync(filePath, "utf-8");
+                const entry = JSON.parse(raw);
+                // Skip expired entries
+                if (now - entry.cachedAt > this.ttlMs) {
+                    fs.unlinkSync(filePath);
+                    continue;
+                }
+                // Only load successful results
+                if (!entry.result.success) {
+                    fs.unlinkSync(filePath);
+                    continue;
+                }
+                this.cache.set(entry.key, {
+                    result: entry.result,
+                    cachedAt: entry.cachedAt,
+                    hitCount: 0,
+                    fileHashes: entry.fileHashes,
+                    commitSha: entry.commitSha,
+                });
+                this.persistedKeys.add(entry.key);
+            }
+            catch {
+                // Skip corrupt files
+            }
+        }
+        // Trim to max capacity
+        while (this.cache.size > this.maxEntries) {
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey !== undefined) {
+                this.cache.delete(oldestKey);
+                this.deleteDiskEntry(oldestKey);
+            }
+        }
+    }
+    /**
+     * Look up a cached result for the given thread parameters.
+     * Returns undefined on cache miss or if context files drifted.
+     */
+    get(task, files, agent, model, repoRoot = "", commitSha = "") {
+        const key = computeCacheKey(task, files, agent, model, repoRoot, commitSha);
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.misses++;
+            return undefined;
+        }
+        // Check TTL expiry
+        if (Date.now() - entry.cachedAt > this.ttlMs) {
+            this.cache.delete(key);
+            this.deleteDiskEntry(key);
+            this.misses++;
+            return undefined;
+        }
+        // Only return successful cached results
+        if (!entry.result.success) {
+            this.misses++;
+            return undefined;
+        }
+        // Task 2.5e: Context hash verification
+        // If context files were recorded, verify that their contents on disk have not drifted
+        if (repoRoot && entry.fileHashes && Object.keys(entry.fileHashes).length > 0) {
+            for (const [file, recordedHash] of Object.entries(entry.fileHashes)) {
+                const absPath = path.isAbsolute(file) ? file : path.join(repoRoot, file);
+                const currentHash = computeFileHash(absPath);
+                if (currentHash !== recordedHash) {
+                    // Stale cache hit with drifted context files -> invalidate and miss
+                    this.cache.delete(key);
+                    this.deleteDiskEntry(key);
+                    this.misses++;
+                    return undefined;
+                }
+            }
+        }
+        this.hits++;
+        entry.hitCount++;
+        this.totalSavedMs += entry.result.durationMs;
+        this.totalSavedUsd += entry.result.estimatedCostUsd;
+        return entry.result;
+    }
+    /**
+     * Store a thread result in the cache.
+     * Only caches successful results — failed threads should be retried.
+     */
+    set(task, files, agent, model, result, repoRoot = "", commitSha = "") {
+        // Don't cache failures
+        if (!result.success)
+            return;
+        // Evict oldest entry if at capacity
+        if (this.cache.size >= this.maxEntries) {
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey !== undefined) {
+                this.cache.delete(oldestKey);
+                this.deleteDiskEntry(oldestKey);
+            }
+        }
+        const key = computeCacheKey(task, files, agent, model, repoRoot, commitSha);
+        const now = Date.now();
+        const fileHashes = repoRoot && files.length > 0 ? computeContextHashes(repoRoot, files) : undefined;
+        this.cache.set(key, {
+            result,
+            cachedAt: now,
+            hitCount: 0,
+            fileHashes,
+            commitSha,
+        });
+        // Persist to disk
+        this.saveDiskEntry(key, result, now, fileHashes, commitSha);
+    }
+    /** Get cache statistics. */
+    getStats() {
+        return {
+            size: this.cache.size,
+            hits: this.hits,
+            misses: this.misses,
+            totalSavedMs: this.totalSavedMs,
+            totalSavedUsd: this.totalSavedUsd,
+            persistedEntries: this.persistedKeys.size,
+        };
+    }
+    /** Clear all cached entries (in-memory and on disk). */
+    clear() {
+        if (this.persistDir) {
+            for (const key of this.cache.keys()) {
+                this.deleteDiskEntry(key);
+            }
+        }
+        this.cache.clear();
+    }
+    // ── Disk persistence ──────────────────────────────────────────────────
+    saveDiskEntry(key, result, cachedAt, fileHashes, commitSha) {
+        if (!this.persistDir)
+            return;
+        try {
+            const entry = { key, result, cachedAt, fileHashes, commitSha };
+            const filePath = path.join(this.persistDir, `${key}.json`);
+            fs.writeFileSync(filePath, JSON.stringify(entry), "utf-8");
+            this.persistedKeys.add(key);
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    deleteDiskEntry(key) {
+        if (!this.persistDir)
+            return;
+        try {
+            const filePath = path.join(this.persistDir, `${key}.json`);
+            if (fs.existsSync(filePath)) {
+                fs.unlinkSync(filePath);
+                this.persistedKeys.delete(key);
+            }
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/threads/cache.js.map

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

package/dist/threads/manager.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Thread manager — spawns and manages coding agent threads in isolated worktrees.
+ *
+ * Features:
+ *   - AsyncSemaphore for proper concurrency gating (no polling)
+ *   - AbortSignal propagation for thread cancellation
+ *   - Per-thread retry logic with exponential backoff
+ *   - Error classification: retryable (transient) vs fatal (permanent)
+ *   - Agent/model re-routing on failure (fallback to alternative combos)
+ *   - Budget tracking and enforcement
+ *   - Per-thread error isolation
+ */
+import type { BudgetState, CompressedResult, SwarmConfig, ThreadConfig, ThreadProgressPhase, ThreadState } from "../core/types.js";
+import type { EpisodicMemory } from "../labs/episodic-memory.js";
+import { WorktreeManager } from "../worktree/manager.js";
+import { type ThreadCacheStats } from "./cache.js";
+/**
+ * Promise-based semaphore for concurrency control.
+ * acquire() resolves when a slot is available, release() frees a slot.
+ */
+export declare class AsyncSemaphore {
+    private current;
+    private readonly max;
+    private waiters;
+    constructor(max: number);
+    acquire(): Promise<void>;
+    release(): void;
+    get activeCount(): number;
+    get waitingCount(): number;
+}
+export type ThreadProgressCallback = (threadId: string, phase: ThreadProgressPhase, detail?: string) => void;
+export type ThreadOutputCallback = (threadId: string, chunk: string) => void;
+export declare class ThreadManager {
+    private repoRoot;
+    private threads;
+    private totalSpawned;
+    private semaphore;
+    private worktreeManager;
+    private config;
+    private budget;
+    private threadCache;
+    private episodicMemory?;
+    private onThreadProgress?;
+    private onThreadOutput?;
+    private sessionAbort?;
+    private threadAbortControllers;
+    constructor(repoRoot: string, config: SwarmConfig, onThreadProgress?: ThreadProgressCallback, sessionAbort?: AbortSignal);
+    /** Set the output streaming callback for live agent output. */
+    setThreadOutputCallback(cb: ThreadOutputCallback): void;
+    /** Set the episodic memory store for recording thread outcomes. */
+    setEpisodicMemory(memory: EpisodicMemory): void;
+    init(): Promise<void>;
+    private getCurrentCommitSha;
+    /**
+     * Spawn a thread — creates a worktree, runs the agent, returns compressed result.
+     * Checks the subthread cache first; on cache hit, returns immediately (Slate-style reuse).
+     * Retries up to config.thread_retries times on failure.
+     * Error-isolated: a failure here never throws — always returns a CompressedResult.
+     */
+    spawnThread(threadConfig: ThreadConfig): Promise<CompressedResult>;
+    /**
+     * Execute a single thread attempt. Acquires semaphore, creates worktree,
+     * runs agent, captures diff, compresses result.
+     */
+    private executeThread;
+    /** Cancel a specific running thread. */
+    cancelThread(threadId: string): boolean;
+    /** Cancel all running threads. */
+    cancelAll(): void;
+    /** Get all thread states. */
+    getThreads(): ThreadState[];
+    /** Get a specific thread's state. */
+    getThread(threadId: string): ThreadState | undefined;
+    /** Restore a completed/failed thread from persisted state (server restart recovery). */
+    restoreThread(state: ThreadState): void;
+    /** Get the worktree manager for merge operations. */
+    getWorktreeManager(): WorktreeManager;
+    /** Get current budget state. */
+    getBudgetState(): BudgetState;
+    /** Get subthread cache stats. */
+    getCacheStats(): ThreadCacheStats;
+    /** Get concurrency stats. */
+    getConcurrencyStats(): {
+        active: number;
+        waiting: number;
+        total: number;
+        max: number;
+    };
+    /** Cleanup all worktrees. */
+    cleanup(): Promise<void>;
+    /** Destroy a specific thread's worktree and branch. */
+    destroyWorktree(threadId: string): Promise<void>;
+    private failResult;
+}