profclaw 0.0.1-beta.3 → 2.3.0

package/dist/agents/auto-memory.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Auto-Memory Extractor
+ *
+ * Extracts durable insights from conversation turns using local
+ * keyword/pattern matching — no LLM calls required.
+ *
+ * Memories are stored at .profclaw/memory/entries.json
+ */
+export type MemoryType = 'decision' | 'preference' | 'context' | 'pattern' | 'error_fix';
+export interface MemoryEntry {
+    id: string;
+    type: MemoryType;
+    content: string;
+    source: {
+        sessionId: string;
+        turnIndex: number;
+    };
+    createdAt: number;
+    /** 0-1, decays over time via prune() */
+    relevance: number;
+}
+export interface TurnInput {
+    userMessage: string;
+    assistantResponse: string;
+    toolCalls?: Array<{
+        name: string;
+        args: unknown;
+        result: unknown;
+    }>;
+    sessionId: string;
+    turnIndex: number;
+}
+export declare class AutoMemoryExtractor {
+    private memoryDir;
+    private entries;
+    /** Tool sequence tracking keyed by sequence fingerprint */
+    private toolSequences;
+    constructor(projectRoot?: string);
+    extractFromTurn(turn: TurnInput): MemoryEntry[];
+    search(query: string, limit?: number): MemoryEntry[];
+    getAll(): MemoryEntry[];
+    save(): void;
+    load(): void;
+    /**
+     * Remove entries that are too old or too low relevance.
+     * Also applies time-based decay to remaining entries.
+     * Returns the count of pruned entries.
+     */
+    prune(maxAgeMs?: number, minRelevance?: number): number;
+    private entriesFilePath;
+    private ensureDir;
+}
+/**
+ * Returns the process-level singleton AutoMemoryExtractor, rooted at cwd().
+ */
+export declare function getAutoMemoryExtractor(): AutoMemoryExtractor;
+/** Exported for test injection. */
+export declare function _resetAutoMemoryExtractorSingleton(): void;
+//# sourceMappingURL=auto-memory.d.ts.map

package/dist/agents/auto-memory.js

@@ -0,0 +1,310 @@
+/**
+ * Auto-Memory Extractor
+ *
+ * Extracts durable insights from conversation turns using local
+ * keyword/pattern matching — no LLM calls required.
+ *
+ * Memories are stored at .profclaw/memory/entries.json
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { randomUUID } from 'node:crypto';
+const EXTRACTION_RULES = [
+    // Decision: "no, use X instead" / "don't do X" / "use X not Y"
+    {
+        type: 'decision',
+        userPatterns: [
+            /\bno[,.]?\s+use\s+(.+?)\s+instead\b/i,
+            /\bdon['']?t\s+use\s+(.+?)[\.,]/i,
+            /\buse\s+(.+?)\s+(?:not|instead of)\s+(.+?)[\.,]/i,
+            /\bplease\s+(?:use|switch to)\s+(.+?)\s+instead\b/i,
+            /\bthat'?s?\s+(?:wrong|incorrect)[,.]?\s+(?:it\s+should\s+be|use)\s+(.+?)[\.,]/i,
+        ],
+        format: (userMsg) => `Decision: ${userMsg.trim()}`,
+    },
+    // Preference: "I prefer X" / "I like X" / "always use X"
+    {
+        type: 'preference',
+        userPatterns: [
+            /\bI\s+prefer\s+(.+?)[\.,]/i,
+            /\bI\s+(?:always|usually)\s+use\s+(.+?)[\.,]/i,
+            /\bI\s+like\s+(?:to\s+use\s+)?(.+?)[\.,]/i,
+            /\balways\s+use\s+(.+?)[\.,]/i,
+            /\bmy\s+preferred\s+(.+?)\s+is\s+(.+?)[\.,]/i,
+        ],
+        format: (userMsg) => `Preference: ${userMsg.trim()}`,
+    },
+    // Context: "this project uses X" / "we use X" / "the stack is X"
+    {
+        type: 'context',
+        userPatterns: [
+            /\bthis\s+project\s+uses?\s+(.+?)[\.,]/i,
+            /\bwe\s+(?:use|are using)\s+(.+?)[\.,]/i,
+            /\bthe\s+stack\s+is\s+(.+?)[\.,]/i,
+            /\bour\s+(?:app|service|backend|frontend)\s+(?:uses?|runs?)\s+(.+?)[\.,]/i,
+            /\bbuilt\s+(?:with|on|using)\s+(.+?)[\.,]/i,
+        ],
+        format: (userMsg) => `Context: ${userMsg.trim()}`,
+    },
+    // Error fix: "the fix was X" / "the issue was X" / "solved by X"
+    {
+        type: 'error_fix',
+        userPatterns: [
+            /\bthe\s+(?:fix|solution)\s+(?:was|is)\s+(.+?)[\.,]/i,
+            /\bthe\s+(?:issue|problem|bug)\s+(?:was|is)\s+(.+?)[\.,]/i,
+            /\bsolved\s+by\s+(.+?)[\.,]/i,
+            /\bfixed\s+(?:by|with|using)\s+(.+?)[\.,]/i,
+        ],
+        assistantPatterns: [
+            /\bthe\s+(?:fix|issue|problem)\s+(?:was|is)\s+(.+?)[\.,]/i,
+            /\bthis\s+(?:was\s+caused|happened)\s+(?:by|because)\s+(.+?)[\.,]/i,
+            /\broot\s+cause[:\s]+(.+?)[\.,]/i,
+        ],
+        format: (userMsg, assistantMsg, match) => {
+            const src = match ? assistantMsg : userMsg;
+            return `Error fix: ${src.trim()}`;
+        },
+    },
+    // Context: assistant explains project facts
+    {
+        type: 'context',
+        assistantPatterns: [
+            /\bthis\s+project\s+uses?\s+(.+?)[\.,]/i,
+            /\byou(?:'re|\s+are)\s+using\s+(.+?)[\.,]/i,
+        ],
+        format: (_userMsg, assistantMsg) => `Context: ${assistantMsg.trim()}`,
+    },
+];
+const PATTERN_THRESHOLD = 3;
+// ---------------------------------------------------------------------------
+// AutoMemoryExtractor
+// ---------------------------------------------------------------------------
+let _instance = null;
+export class AutoMemoryExtractor {
+    memoryDir;
+    entries;
+    /** Tool sequence tracking keyed by sequence fingerprint */
+    toolSequences;
+    constructor(projectRoot) {
+        const root = projectRoot ?? process.cwd();
+        this.memoryDir = path.join(root, '.profclaw', 'memory');
+        this.entries = [];
+        this.toolSequences = new Map();
+        this.load();
+    }
+    // -------------------------------------------------------------------------
+    // Core: extract memories from a completed turn
+    // -------------------------------------------------------------------------
+    extractFromTurn(turn) {
+        const extracted = [];
+        const { userMessage, assistantResponse, toolCalls, sessionId, turnIndex } = turn;
+        // Apply each rule
+        for (const rule of EXTRACTION_RULES) {
+            let matchedUser = null;
+            let matchedAssistant = null;
+            if (rule.userPatterns) {
+                for (const pat of rule.userPatterns) {
+                    const m = userMessage.match(pat);
+                    if (m) {
+                        matchedUser = m;
+                        break;
+                    }
+                }
+            }
+            if (rule.assistantPatterns) {
+                for (const pat of rule.assistantPatterns) {
+                    const m = assistantResponse.match(pat);
+                    if (m) {
+                        matchedAssistant = m;
+                        break;
+                    }
+                }
+            }
+            // Determine if the rule fires
+            let fires = false;
+            let matchRef = null;
+            if (rule.userPatterns && rule.assistantPatterns) {
+                // Both required when both pattern sets are defined and requireBoth is true
+                if (rule.requireBoth) {
+                    fires = matchedUser !== null && matchedAssistant !== null;
+                    matchRef = matchedAssistant;
+                }
+                else {
+                    fires = matchedUser !== null || matchedAssistant !== null;
+                    matchRef = matchedAssistant ?? matchedUser;
+                }
+            }
+            else if (rule.userPatterns) {
+                fires = matchedUser !== null;
+                matchRef = matchedUser;
+            }
+            else if (rule.assistantPatterns) {
+                fires = matchedAssistant !== null;
+                matchRef = matchedAssistant;
+            }
+            if (!fires)
+                continue;
+            const content = rule.format(userMessage, assistantResponse, matchRef);
+            // Avoid duplicate entries with identical content
+            if (this.entries.some((e) => e.content === content))
+                continue;
+            const entry = {
+                id: randomUUID(),
+                type: rule.type,
+                content,
+                source: { sessionId, turnIndex },
+                createdAt: Date.now(),
+                relevance: 1.0,
+            };
+            extracted.push(entry);
+            this.entries.push(entry);
+        }
+        // Pattern memory: detect repeated tool sequences
+        if (toolCalls && toolCalls.length >= 2) {
+            const sequence = toolCalls.map((tc) => tc.name).join(' → ');
+            const existing = this.toolSequences.get(sequence);
+            if (existing) {
+                existing.count += 1;
+                existing.lastTurnIndex = turnIndex;
+                if (existing.count === PATTERN_THRESHOLD) {
+                    const content = `Pattern: tool chain "${sequence}" used ${existing.count}+ times`;
+                    if (!this.entries.some((e) => e.content === content)) {
+                        const entry = {
+                            id: randomUUID(),
+                            type: 'pattern',
+                            content,
+                            source: { sessionId, turnIndex },
+                            createdAt: Date.now(),
+                            relevance: 1.0,
+                        };
+                        extracted.push(entry);
+                        this.entries.push(entry);
+                    }
+                }
+            }
+            else {
+                this.toolSequences.set(sequence, {
+                    sequence,
+                    count: 1,
+                    lastTurnIndex: turnIndex,
+                    sessionId,
+                });
+            }
+        }
+        if (extracted.length > 0) {
+            this.save();
+        }
+        return extracted;
+    }
+    // -------------------------------------------------------------------------
+    // Search: keyword matching + relevance scoring
+    // -------------------------------------------------------------------------
+    search(query, limit = 10) {
+        if (!query.trim())
+            return this.entries.slice(0, limit);
+        const words = query
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((w) => w.length >= 2);
+        const scored = this.entries.map((entry) => {
+            const lower = entry.content.toLowerCase();
+            const matchCount = words.filter((w) => lower.includes(w)).length;
+            const score = (matchCount / Math.max(words.length, 1)) * entry.relevance;
+            return { entry, score };
+        });
+        return scored
+            .filter(({ score }) => score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit)
+            .map(({ entry }) => entry);
+    }
+    // -------------------------------------------------------------------------
+    // Accessors
+    // -------------------------------------------------------------------------
+    getAll() {
+        return [...this.entries];
+    }
+    // -------------------------------------------------------------------------
+    // Persistence
+    // -------------------------------------------------------------------------
+    save() {
+        try {
+            this.ensureDir();
+            const filePath = this.entriesFilePath();
+            fs.writeFileSync(filePath, JSON.stringify({ entries: this.entries, sequences: Array.from(this.toolSequences.entries()) }, null, 2), 'utf8');
+        }
+        catch (err) {
+            console.error('[AutoMemoryExtractor] Failed to save:', err);
+        }
+    }
+    load() {
+        const filePath = this.entriesFilePath();
+        if (!fs.existsSync(filePath))
+            return;
+        try {
+            const raw = fs.readFileSync(filePath, 'utf8');
+            const parsed = JSON.parse(raw);
+            this.entries = Array.isArray(parsed.entries) ? parsed.entries : [];
+            if (Array.isArray(parsed.sequences)) {
+                this.toolSequences = new Map(parsed.sequences);
+            }
+        }
+        catch (err) {
+            console.error('[AutoMemoryExtractor] Failed to load:', err);
+            this.entries = [];
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Pruning
+    // -------------------------------------------------------------------------
+    /**
+     * Remove entries that are too old or too low relevance.
+     * Also applies time-based decay to remaining entries.
+     * Returns the count of pruned entries.
+     */
+    prune(maxAgeMs = 30 * 24 * 60 * 60 * 1000, minRelevance = 0.1) {
+        const now = Date.now();
+        const before = this.entries.length;
+        this.entries = this.entries
+            .map((e) => {
+            // Exponential decay: half-life = maxAgeMs / 2
+            const ageFraction = (now - e.createdAt) / maxAgeMs;
+            const decayed = e.relevance * Math.exp(-Math.LN2 * ageFraction);
+            return { ...e, relevance: Math.max(0, decayed) };
+        })
+            .filter((e) => {
+            const tooOld = now - e.createdAt > maxAgeMs;
+            const tooWeak = e.relevance < minRelevance;
+            return !tooOld && !tooWeak;
+        });
+        const pruned = before - this.entries.length;
+        if (pruned > 0)
+            this.save();
+        return pruned;
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    entriesFilePath() {
+        return path.join(this.memoryDir, 'entries.json');
+    }
+    ensureDir() {
+        if (!fs.existsSync(this.memoryDir)) {
+            fs.mkdirSync(this.memoryDir, { recursive: true });
+        }
+    }
+}
+/**
+ * Returns the process-level singleton AutoMemoryExtractor, rooted at cwd().
+ */
+export function getAutoMemoryExtractor() {
+    if (!_instance) {
+        _instance = new AutoMemoryExtractor();
+    }
+    return _instance;
+}
+/** Exported for test injection. */
+export function _resetAutoMemoryExtractorSingleton() {
+    _instance = null;
+}
+//# sourceMappingURL=auto-memory.js.map

package/dist/agents/checkpoint-manager.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 type { ModelMessage } from 'ai';
+export interface ExecutorCheckpoint {
+    /** Session that produced this checkpoint */
+    sessionId: string;
+    /** Human-readable description of the original task */
+    taskDescription?: string;
+    /** How many steps have been executed so far */
+    currentStep: number;
+    /** Expected total steps (best-effort estimate) */
+    totalSteps: number;
+    /** Full message history up to this point */
+    messages: ModelMessage[];
+    /** Cumulative tokens consumed */
+    tokensUsed: number;
+    /** Estimated dollar cost so far */
+    estimatedCost: number;
+    /** Every tool call made so far: name, success flag, and the step it ran in */
+    toolCallHistory: Array<{
+        name: string;
+        success: boolean;
+        step: number;
+    }>;
+    /** Files that have already been processed (for file-iteration tasks) */
+    completedFiles?: string[];
+    /** Free-text description of what still needs to happen */
+    remainingWork?: string;
+    /** Unix epoch ms — when the checkpoint was first created */
+    createdAt: number;
+    /** Unix epoch ms — when the checkpoint was last saved */
+    updatedAt: number;
+}
+/** Lightweight summary returned by list() */
+export interface CheckpointSummary {
+    sessionId: string;
+    taskDescription?: string;
+    step: number;
+    updatedAt: number;
+}
+export declare class CheckpointManager {
+    private readonly checkpointsDir;
+    constructor(projectRoot?: string);
+    private filePath;
+    private ensureDir;
+    /**
+     * Persist a checkpoint to disk.  Creates .profclaw/checkpoints/ if needed.
+     */
+    save(checkpoint: ExecutorCheckpoint): Promise<void>;
+    /**
+     * Load a previously saved checkpoint.  Returns null when none exists.
+     */
+    load(sessionId: string): Promise<ExecutorCheckpoint | null>;
+    /**
+     * List all checkpoints, sorted newest first.
+     */
+    list(): Promise<CheckpointSummary[]>;
+    /**
+     * Delete a checkpoint after the session has completed successfully.
+     */
+    remove(sessionId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    findResumable(taskDescription: string): Promise<ExecutorCheckpoint | null>;
+}
+export declare function getCheckpointManager(projectRoot?: string): CheckpointManager;
+//# sourceMappingURL=checkpoint-manager.d.ts.map

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