profclaw 2.0.0 → 2.3.0

package/dist/agents/checkpoint-manager.js

@@ -0,0 +1,156 @@
+/**
+ * Checkpoint Manager
+ *
+ * Saves and restores executor state so long-running agentic sessions can be
+ * interrupted and resumed without losing progress.  Checkpoints live at
+ * .profclaw/checkpoints/<sessionId>.json relative to the project root (or the
+ * current working directory when no root is supplied).
+ */
+import { mkdir, readFile, writeFile, unlink, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { logger } from '../utils/logger.js';
+// ─── CheckpointManager ────────────────────────────────────────────────────────
+export class CheckpointManager {
+    checkpointsDir;
+    constructor(projectRoot) {
+        const root = projectRoot ? resolve(projectRoot) : process.cwd();
+        this.checkpointsDir = join(root, '.profclaw', 'checkpoints');
+    }
+    // ── Private helpers ──────────────────────────────────────────────────────
+    filePath(sessionId) {
+        return join(this.checkpointsDir, `${sessionId}.json`);
+    }
+    async ensureDir() {
+        if (!existsSync(this.checkpointsDir)) {
+            await mkdir(this.checkpointsDir, { recursive: true });
+        }
+    }
+    // ── Public API ───────────────────────────────────────────────────────────
+    /**
+     * Persist a checkpoint to disk.  Creates .profclaw/checkpoints/ if needed.
+     */
+    async save(checkpoint) {
+        await this.ensureDir();
+        const path = this.filePath(checkpoint.sessionId);
+        const payload = JSON.stringify({ ...checkpoint, updatedAt: Date.now() }, null, 2);
+        await writeFile(path, payload, 'utf-8');
+        logger.debug('[CheckpointManager] Saved checkpoint', {
+            sessionId: checkpoint.sessionId,
+            step: checkpoint.currentStep,
+            path,
+        });
+    }
+    /**
+     * Load a previously saved checkpoint.  Returns null when none exists.
+     */
+    async load(sessionId) {
+        const path = this.filePath(sessionId);
+        try {
+            const raw = await readFile(path, 'utf-8');
+            const parsed = JSON.parse(raw);
+            logger.debug('[CheckpointManager] Loaded checkpoint', {
+                sessionId,
+                step: parsed.currentStep,
+            });
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * List all checkpoints, sorted newest first.
+     */
+    async list() {
+        if (!existsSync(this.checkpointsDir))
+            return [];
+        let files;
+        try {
+            files = await readdir(this.checkpointsDir);
+        }
+        catch {
+            return [];
+        }
+        const summaries = [];
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            try {
+                const raw = await readFile(join(this.checkpointsDir, file), 'utf-8');
+                const cp = JSON.parse(raw);
+                summaries.push({
+                    sessionId: cp.sessionId,
+                    taskDescription: cp.taskDescription,
+                    step: cp.currentStep,
+                    updatedAt: cp.updatedAt,
+                });
+            }
+            catch {
+                // Skip malformed files
+            }
+        }
+        return summaries.sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    /**
+     * Delete a checkpoint after the session has completed successfully.
+     */
+    async remove(sessionId) {
+        const path = this.filePath(sessionId);
+        try {
+            await unlink(path);
+            logger.debug('[CheckpointManager] Removed checkpoint', { sessionId });
+        }
+        catch {
+            // Already gone — not an error
+        }
+    }
+    /**
+     * Find a resumable checkpoint whose taskDescription loosely matches the
+     * given description (case-insensitive substring + word overlap heuristic).
+     * Returns the most recently updated match, or null if nothing qualifies.
+     */
+    async findResumable(taskDescription) {
+        const all = await this.list();
+        if (all.length === 0)
+            return null;
+        const needle = taskDescription.toLowerCase();
+        const needleWords = new Set(needle.split(/\W+/).filter(Boolean));
+        let bestScore = 0;
+        let bestId = null;
+        for (const summary of all) {
+            if (!summary.taskDescription)
+                continue;
+            const hay = summary.taskDescription.toLowerCase();
+            // Substring match is a strong signal
+            if (hay.includes(needle) || needle.includes(hay)) {
+                // Prefer the most recently updated substring match
+                if (summary.updatedAt > (bestScore === 2 ? 0 : -1)) {
+                    bestScore = 2;
+                    bestId = summary.sessionId;
+                }
+                continue;
+            }
+            // Word-overlap fallback
+            const hayWords = hay.split(/\W+/).filter(Boolean);
+            const overlap = hayWords.filter((w) => needleWords.has(w)).length;
+            const ratio = needleWords.size > 0 ? overlap / needleWords.size : 0;
+            if (ratio >= 0.5 && ratio > bestScore) {
+                bestScore = ratio;
+                bestId = summary.sessionId;
+            }
+        }
+        if (!bestId)
+            return null;
+        return this.load(bestId);
+    }
+}
+// ─── Singleton ────────────────────────────────────────────────────────────────
+let _instance;
+export function getCheckpointManager(projectRoot) {
+    if (!_instance) {
+        _instance = new CheckpointManager(projectRoot);
+    }
+    return _instance;
+}
+//# sourceMappingURL=checkpoint-manager.js.map

package/dist/agents/circuit-breaker.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Tool Circuit Breaker
+ *
+ * Prevents tools from being called repeatedly when they are failing.
+ * Implements the standard circuit breaker pattern:
+ *   closed → (3 failures in 2 min) → open → (cooldown expires) → half-open
+ *   half-open → (1 success) → closed
+ *   half-open → (1 failure) → open (doubled cooldown)
+ */
+export type CircuitBreakerStateValue = 'closed' | 'open' | 'half-open';
+export interface CircuitBreakerState {
+    state: CircuitBreakerStateValue;
+    failureCount: number;
+    lastFailureAt: number;
+    cooldownMs: number;
+}
+export interface CanExecuteResult {
+    allowed: boolean;
+    reason?: string;
+}
+export declare class ToolCircuitBreaker {
+    private breakers;
+    private readonly failureThreshold;
+    private readonly windowMs;
+    constructor(failureThreshold?: number, windowMs?: number);
+    /**
+     * Check whether a tool is allowed to execute.
+     * Transitions open → half-open when the cooldown has expired.
+     */
+    canExecute(toolName: string): CanExecuteResult;
+    /**
+     * Record a successful tool execution.
+     * In half-open state this closes the circuit.
+     */
+    recordSuccess(toolName: string): void;
+    /**
+     * Record a failed tool execution.
+     * Counts failures within the time window and trips the breaker when the
+     * threshold is reached. In half-open state it immediately re-opens with
+     * a doubled cooldown.
+     */
+    recordFailure(toolName: string): void;
+    /**
+     * Reset the circuit breaker for a specific tool, or all tools if no name is given.
+     */
+    reset(toolName?: string): void;
+    /**
+     * Return a deep snapshot of all breaker states.
+     * Mutations to the live breakers do not affect the returned map.
+     */
+    getStatus(): Map<string, CircuitBreakerState>;
+    private getOrCreate;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/agents/circuit-breaker.js

@@ -0,0 +1,153 @@
+/**
+ * Tool Circuit Breaker
+ *
+ * Prevents tools from being called repeatedly when they are failing.
+ * Implements the standard circuit breaker pattern:
+ *   closed → (3 failures in 2 min) → open → (cooldown expires) → half-open
+ *   half-open → (1 success) → closed
+ *   half-open → (1 failure) → open (doubled cooldown)
+ */
+import { logger } from '../utils/logger.js';
+// Constants
+const DEFAULT_FAILURE_THRESHOLD = 3;
+const DEFAULT_WINDOW_MS = 120_000; // 2 minutes
+const INITIAL_COOLDOWN_MS = 5_000;
+const MAX_COOLDOWN_MS = 60_000;
+function defaultBreakerState() {
+    return {
+        state: 'closed',
+        failureCount: 0,
+        lastFailureAt: 0,
+        cooldownMs: INITIAL_COOLDOWN_MS,
+    };
+}
+// Circuit Breaker
+export class ToolCircuitBreaker {
+    breakers;
+    failureThreshold;
+    windowMs;
+    constructor(failureThreshold = DEFAULT_FAILURE_THRESHOLD, windowMs = DEFAULT_WINDOW_MS) {
+        this.breakers = new Map();
+        this.failureThreshold = failureThreshold;
+        this.windowMs = windowMs;
+    }
+    /**
+     * Check whether a tool is allowed to execute.
+     * Transitions open → half-open when the cooldown has expired.
+     */
+    canExecute(toolName) {
+        const breaker = this.getOrCreate(toolName);
+        const now = Date.now();
+        if (breaker.state === 'closed') {
+            return { allowed: true };
+        }
+        if (breaker.state === 'open') {
+            const elapsed = now - breaker.lastFailureAt;
+            if (elapsed >= breaker.cooldownMs) {
+                // Transition to half-open to allow a probe call
+                breaker.state = 'half-open';
+                logger.debug('[CircuitBreaker] Transitioning to half-open', {
+                    tool: toolName,
+                    elapsed,
+                    cooldownMs: breaker.cooldownMs,
+                });
+                return { allowed: true };
+            }
+            const remainingMs = breaker.cooldownMs - elapsed;
+            return {
+                allowed: false,
+                reason: `Circuit breaker open for ${toolName}: too many recent failures. Retry in ${Math.ceil(remainingMs / 1000)}s.`,
+            };
+        }
+        // half-open: allow one probe through
+        return { allowed: true };
+    }
+    /**
+     * Record a successful tool execution.
+     * In half-open state this closes the circuit.
+     */
+    recordSuccess(toolName) {
+        const breaker = this.getOrCreate(toolName);
+        if (breaker.state === 'half-open') {
+            logger.info('[CircuitBreaker] Probe succeeded, closing circuit', { tool: toolName });
+            breaker.state = 'closed';
+            breaker.failureCount = 0;
+            breaker.cooldownMs = INITIAL_COOLDOWN_MS;
+        }
+        else if (breaker.state === 'closed') {
+            // Reset failure count on success within the window
+            breaker.failureCount = 0;
+        }
+    }
+    /**
+     * Record a failed tool execution.
+     * Counts failures within the time window and trips the breaker when the
+     * threshold is reached. In half-open state it immediately re-opens with
+     * a doubled cooldown.
+     */
+    recordFailure(toolName) {
+        const breaker = this.getOrCreate(toolName);
+        const now = Date.now();
+        if (breaker.state === 'half-open') {
+            // Probe failed — re-open with doubled cooldown
+            breaker.cooldownMs = Math.min(breaker.cooldownMs * 2, MAX_COOLDOWN_MS);
+            breaker.state = 'open';
+            breaker.lastFailureAt = now;
+            logger.warn('[CircuitBreaker] Probe failed, re-opening circuit', {
+                tool: toolName,
+                cooldownMs: breaker.cooldownMs,
+            });
+            return;
+        }
+        // In closed state, check if previous failures are still within the window
+        const withinWindow = breaker.lastFailureAt > 0 && now - breaker.lastFailureAt <= this.windowMs;
+        if (withinWindow) {
+            breaker.failureCount++;
+        }
+        else {
+            // Failures outside the window don't count; start a fresh count
+            breaker.failureCount = 1;
+        }
+        breaker.lastFailureAt = now;
+        if (breaker.failureCount >= this.failureThreshold) {
+            breaker.state = 'open';
+            logger.warn('[CircuitBreaker] Threshold reached, opening circuit', {
+                tool: toolName,
+                failureCount: breaker.failureCount,
+                cooldownMs: breaker.cooldownMs,
+            });
+        }
+    }
+    /**
+     * Reset the circuit breaker for a specific tool, or all tools if no name is given.
+     */
+    reset(toolName) {
+        if (toolName !== undefined) {
+            this.breakers.set(toolName, defaultBreakerState());
+        }
+        else {
+            this.breakers.clear();
+        }
+    }
+    /**
+     * Return a deep snapshot of all breaker states.
+     * Mutations to the live breakers do not affect the returned map.
+     */
+    getStatus() {
+        const snapshot = new Map();
+        for (const [key, value] of this.breakers) {
+            snapshot.set(key, { ...value });
+        }
+        return snapshot;
+    }
+    // Private helpers
+    getOrCreate(toolName) {
+        let breaker = this.breakers.get(toolName);
+        if (!breaker) {
+            breaker = defaultBreakerState();
+            this.breakers.set(toolName, breaker);
+        }
+        return breaker;
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/agents/context-compactor.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Context Compactor
+ *
+ * Compresses old conversation turns into a structured markdown summary when
+ * the estimated token count crosses a configurable threshold.
+ *
+ * Two modes:
+ *  - Local heuristic (default): pure extraction, no LLM calls.
+ *  - LLM-powered (opt-in): uses an injected apiCall function to produce a
+ *    richer natural-language summary.
+ */
+import type { ModelMessage } from "ai";
+export interface CompactionConfig {
+    /** Total token budget for the context window. Default: 100_000 */
+    maxContextTokens: number;
+    /** Trigger compaction once estimated tokens exceed this value. Default: 70_000 */
+    compactionThreshold: number;
+    /** Number of most-recent turns (user+assistant pairs) to preserve verbatim. Default: 5 */
+    preserveRecentTurns: number;
+    /** Maximum tokens for the generated summary message. Default: 2_000 */
+    summaryMaxTokens: number;
+    /**
+     * When true, `compact()` will delegate to `compactWithLLM()` if an
+     * `apiCall` function is provided at call time. Default: false.
+     */
+    useLLM?: boolean;
+    /** Cheap model to use for LLM summarisation (e.g. 'llama3.2'). */
+    summaryModel?: string;
+    /** Provider for the summarisation model (e.g. 'ollama'). */
+    summaryProvider?: string;
+}
+export interface CompactionResult {
+    messages: ModelMessage[];
+    compacted: boolean;
+    originalTokens: number;
+    compactedTokens: number;
+    turnsCompacted: number;
+}
+export declare class ContextCompactor {
+    private config;
+    constructor(config?: Partial<CompactionConfig>);
+    /**
+     * Estimate the token count for a list of messages using the 4-chars-per-token
+     * heuristic.
+     */
+    estimateTokens(messages: ModelMessage[]): number;
+    /**
+     * Compact the message list if it exceeds the compaction threshold.
+     *
+     * Strategy:
+     *  1. Identify the most-recent N turns to preserve verbatim.
+     *  2. Summarise all older messages into a single system-role summary message.
+     *  3. Return the summary + preserved recent messages.
+     *
+     * When `config.useLLM` is true and `apiCall` is provided, delegates to
+     * `compactWithLLM()` for a richer natural-language summary.
+     * Falls back to local heuristic summarisation if the LLM call fails.
+     */
+    compact(messages: ModelMessage[], apiCall?: (prompt: string) => Promise<string>): Promise<CompactionResult>;
+    /**
+     * Compact using an injected LLM call for richer summarisation.
+     *
+     * The `apiCall` function is supplied by the caller so this class remains
+     * free of any specific API client dependency.
+     */
+    compactWithLLM(messages: ModelMessage[], apiCall: (prompt: string) => Promise<string>): Promise<CompactionResult>;
+    /** Local heuristic compaction (no LLM). */
+    private _compactLocal;
+}
+//# sourceMappingURL=context-compactor.d.ts.map