profclaw 2.0.0 → 2.3.0

package/dist/agents/agent-summary.js

@@ -0,0 +1,176 @@
+/**
+ * Agent Summary Tracker
+ *
+ * Provides real-time 1-2 word progress summaries of what agents are doing,
+ * suitable for display in CLI/UI progress indicators.
+ */
+import path from 'node:path';
+function extractFilename(filePath) {
+    if (typeof filePath !== 'string' || filePath.length === 0)
+        return undefined;
+    return path.basename(filePath);
+}
+function extractCommand(command) {
+    if (typeof command !== 'string' || command.length === 0)
+        return undefined;
+    // Truncate long commands to first 40 chars
+    const trimmed = command.trim();
+    return trimmed.length > 40 ? `${trimmed.substring(0, 40)}…` : trimmed;
+}
+function extractQuery(query) {
+    if (typeof query !== 'string' || query.length === 0)
+        return undefined;
+    const trimmed = query.trim();
+    return trimmed.length > 30 ? `${trimmed.substring(0, 30)}…` : trimmed;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function toArgs(input) {
+    return isRecord(input) ? input : {};
+}
+export class AgentSummaryTracker {
+    summaries = new Map();
+    broadcaster;
+    registerSSEBroadcaster(broadcaster) {
+        this.broadcaster = broadcaster;
+    }
+    start(sessionId) {
+        const now = Date.now();
+        const summary = {
+            sessionId,
+            status: 'idle',
+            currentAction: 'Starting',
+            stepCount: 0,
+            tokensUsed: 0,
+            startedAt: now,
+            updatedAt: now,
+        };
+        this.summaries.set(sessionId, summary);
+        this.broadcaster?.('agent:summary', summary);
+    }
+    update(sessionId, updates) {
+        const existing = this.summaries.get(sessionId);
+        if (!existing)
+            return;
+        const updated = {
+            ...existing,
+            ...updates,
+            sessionId, // always preserve original sessionId
+            updatedAt: Date.now(),
+        };
+        this.summaries.set(sessionId, updated);
+        this.broadcaster?.('agent:summary', updated);
+    }
+    /**
+     * Auto-generate a human-readable summary from a tool call.
+     *
+     * Examples:
+     *   read_file({ path: '/src/auth.ts' })       → "Reading auth.ts"
+     *   write_file({ path: '/src/fix.ts' })        → "Writing fix.ts"
+     *   bash({ command: 'npm test' })              → "Running npm test"
+     *   search_files({ query: 'login' })           → "Searching for 'login'"
+     *   git_commit({ message: 'fix: auth' })       → "Committing changes"
+     *   complete_task                              → "Completing task"
+     *   default                                    → "Using {toolName}"
+     */
+    summarizeToolCall(sessionId, toolName, args) {
+        const argsRecord = toArgs(args);
+        // File reads
+        if (toolName === 'read_file' || toolName === 'Read') {
+            const filename = extractFilename(argsRecord['path'] ?? argsRecord['file_path']);
+            return filename ? `Reading ${filename}` : 'Reading file';
+        }
+        // File writes
+        if (toolName === 'write_file' || toolName === 'Write' || toolName === 'create_file') {
+            const filename = extractFilename(argsRecord['path'] ?? argsRecord['file_path']);
+            return filename ? `Writing ${filename}` : 'Writing file';
+        }
+        // File edits
+        if (toolName === 'edit_file' || toolName === 'Edit' || toolName === 'str_replace_editor') {
+            const filename = extractFilename(argsRecord['path'] ?? argsRecord['file_path']);
+            return filename ? `Editing ${filename}` : 'Editing file';
+        }
+        // Bash/shell execution
+        if (toolName === 'bash' || toolName === 'Bash' || toolName === 'execute_command' || toolName === 'run_command') {
+            const cmd = extractCommand(argsRecord['command'] ?? argsRecord['cmd']);
+            return cmd ? `Running ${cmd}` : 'Running command';
+        }
+        // File search / glob
+        if (toolName === 'search_files' || toolName === 'Glob' || toolName === 'glob') {
+            const query = extractQuery(argsRecord['query'] ?? argsRecord['pattern']);
+            return query ? `Searching for '${query}'` : 'Searching files';
+        }
+        // Content search / grep
+        if (toolName === 'grep' || toolName === 'Grep' || toolName === 'search_content') {
+            const query = extractQuery(argsRecord['query'] ?? argsRecord['pattern']);
+            return query ? `Searching for '${query}'` : 'Searching content';
+        }
+        // Git operations
+        if (toolName === 'git_commit' || toolName === 'git_push') {
+            return 'Committing changes';
+        }
+        if (toolName === 'git_status') {
+            return 'Checking git status';
+        }
+        if (toolName === 'git_diff') {
+            return 'Reviewing changes';
+        }
+        // Task completion
+        if (toolName === 'complete_task') {
+            return 'Completing task';
+        }
+        // Web fetch / browse
+        if (toolName === 'web_fetch' || toolName === 'WebFetch' || toolName === 'fetch_url' || toolName === 'browse') {
+            const url = argsRecord['url'] ?? argsRecord['href'];
+            if (typeof url === 'string' && url.length > 0) {
+                try {
+                    const { hostname } = new URL(url);
+                    return `Fetching ${hostname}`;
+                }
+                catch {
+                    // malformed URL - fall through to default
+                }
+            }
+            return 'Fetching URL';
+        }
+        // Task tool — spawn sub-agent
+        if (toolName === 'Task' || toolName === 'task') {
+            return 'Spawning agent';
+        }
+        // Default fallback: humanize camelCase/snake_case tool name
+        const humanized = toolName
+            .replace(/_/g, ' ')
+            .replace(/([a-z])([A-Z])/g, '$1 $2')
+            .toLowerCase();
+        return `Using ${humanized}`;
+    }
+    get(sessionId) {
+        return this.summaries.get(sessionId);
+    }
+    getAll() {
+        return Array.from(this.summaries.values());
+    }
+    end(sessionId) {
+        const existing = this.summaries.get(sessionId);
+        if (existing) {
+            this.broadcaster?.('agent:summary', {
+                ...existing,
+                status: 'idle',
+                currentAction: 'Done',
+                updatedAt: Date.now(),
+                ended: true,
+            });
+        }
+        this.summaries.delete(sessionId);
+    }
+}
+// Singleton instance
+let tracker;
+export function getAgentSummaryTracker() {
+    if (!tracker) {
+        tracker = new AgentSummaryTracker();
+    }
+    return tracker;
+}
+//# sourceMappingURL=agent-summary.js.map

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