profclaw 0.0.1-beta.3 → 2.3.0

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

package/dist/agents/context-compactor.js

@@ -0,0 +1,361 @@
+/**
+ * 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.
+ */
+// ─── Internals ────────────────────────────────────────────────────────────────
+const DEFAULT_CONFIG = {
+    maxContextTokens: 100_000,
+    compactionThreshold: 70_000,
+    preserveRecentTurns: 5,
+    summaryMaxTokens: 2_000,
+};
+/** Rough character-to-token ratio used throughout (4 chars ≈ 1 token). */
+const CHARS_PER_TOKEN = 4;
+// ─── Helper utilities ─────────────────────────────────────────────────────────
+function messageToText(message) {
+    if (typeof message.content === "string") {
+        return message.content;
+    }
+    if (Array.isArray(message.content)) {
+        return message.content
+            .map((part) => {
+            if (typeof part === "string")
+                return part;
+            // TextPart
+            if (typeof part === "object" &&
+                part !== null &&
+                "type" in part &&
+                part.type === "text" &&
+                "text" in part) {
+                return String(part.text);
+            }
+            // ToolCallPart
+            if (typeof part === "object" &&
+                part !== null &&
+                "type" in part &&
+                part.type === "tool-call") {
+                const tc = part;
+                return `[tool_call: ${tc.toolName}(${JSON.stringify(tc.args ?? {})})]`;
+            }
+            // ToolResultPart
+            if (typeof part === "object" &&
+                part !== null &&
+                "type" in part &&
+                part.type === "tool-result") {
+                const tr = part;
+                return `[tool_result: ${tr.toolName ?? "unknown"} → ${JSON.stringify(tr.result ?? null)}]`;
+            }
+            return JSON.stringify(part);
+        })
+            .join(" ");
+    }
+    return "";
+}
+/** Extract file paths that were read or written during a set of messages. */
+function extractFilePaths(messages) {
+    const paths = new Set();
+    const filePattern = /(?:read|write|edit|create|modify)\s+([`"']?[\w./\-_]+\.[a-zA-Z]+[`"']?)/gi;
+    for (const msg of messages) {
+        const text = messageToText(msg);
+        let match;
+        while ((match = filePattern.exec(text)) !== null) {
+            paths.add(match[1].replace(/[`"']/g, ""));
+        }
+    }
+    return Array.from(paths);
+}
+function extractToolCalls(messages) {
+    const calls = [];
+    for (const msg of messages) {
+        if (!Array.isArray(msg.content))
+            continue;
+        for (const part of msg.content) {
+            if (typeof part !== "object" ||
+                part === null ||
+                !("type" in part)) {
+                continue;
+            }
+            const typed = part;
+            if (typed.type === "tool-call") {
+                const tc = part;
+                const argKeys = Object.keys(tc.args ?? {}).slice(0, 3).join(", ");
+                calls.push({
+                    name: tc.toolName,
+                    argsSummary: argKeys ? `{${argKeys}}` : "(no args)",
+                    outcome: "called",
+                });
+            }
+            if (typed.type === "tool-result") {
+                const tr = part;
+                const last = [...calls].reverse().find((c) => c.name === (tr.toolName ?? ""));
+                const resultText = typeof tr.result === "string"
+                    ? tr.result.slice(0, 120)
+                    : JSON.stringify(tr.result ?? null).slice(0, 120);
+                if (last) {
+                    last.outcome = tr.isError === true ? `error: ${resultText}` : `ok: ${resultText}`;
+                }
+                else {
+                    calls.push({
+                        name: tr.toolName ?? "unknown",
+                        argsSummary: "",
+                        outcome: tr.isError === true ? `error: ${resultText}` : `ok: ${resultText}`,
+                    });
+                }
+            }
+        }
+    }
+    return calls;
+}
+/** Extract the apparent user goals from user-role messages. */
+function extractUserGoals(messages) {
+    const goals = [];
+    for (const msg of messages) {
+        if (msg.role !== "user")
+            continue;
+        const text = messageToText(msg).trim();
+        if (text.length > 0) {
+            // Keep only the first 200 chars per turn to stay concise
+            goals.push(text.slice(0, 200) + (text.length > 200 ? "…" : ""));
+        }
+    }
+    return goals;
+}
+/** Build a structured markdown summary capped at approximately maxTokens. */
+function buildSummary(messages, maxTokens) {
+    const maxChars = maxTokens * CHARS_PER_TOKEN;
+    const userGoals = extractUserGoals(messages);
+    const toolCalls = extractToolCalls(messages);
+    const filePaths = extractFilePaths(messages);
+    const lines = [
+        "# Conversation Summary (compacted context)",
+        "",
+        "## User Requests / Goals",
+    ];
+    if (userGoals.length > 0) {
+        for (const goal of userGoals) {
+            lines.push(`- ${goal}`);
+        }
+    }
+    else {
+        lines.push("- (no explicit user messages in compacted range)");
+    }
+    lines.push("", "## Tool Calls & Outcomes");
+    if (toolCalls.length > 0) {
+        for (const tc of toolCalls) {
+            lines.push(`- **${tc.name}** ${tc.argsSummary} → ${tc.outcome}`);
+        }
+    }
+    else {
+        lines.push("- (no tool calls in compacted range)");
+    }
+    lines.push("", "## Files Read / Written / Modified");
+    if (filePaths.length > 0) {
+        for (const fp of filePaths) {
+            lines.push(`- \`${fp}\``);
+        }
+    }
+    else {
+        lines.push("- (no file operations detected)");
+    }
+    lines.push("", "## Key Decisions");
+    // Look for assistant messages that contain decision-like keywords
+    const decisions = [];
+    for (const msg of messages) {
+        if (msg.role !== "assistant")
+            continue;
+        const text = messageToText(msg).trim();
+        if (/decided|chosen|using|selected|approach|strategy|plan/i.test(text) &&
+            text.length > 20) {
+            decisions.push(text.slice(0, 200) + (text.length > 200 ? "…" : ""));
+        }
+    }
+    if (decisions.length > 0) {
+        for (const d of decisions) {
+            lines.push(`- ${d}`);
+        }
+    }
+    else {
+        lines.push("- (no explicit decisions recorded)");
+    }
+    const full = lines.join("\n");
+    // Trim to maxChars if necessary
+    return full.length > maxChars ? full.slice(0, maxChars) + "\n…(truncated)" : full;
+}
+// ─── ContextCompactor ─────────────────────────────────────────────────────────
+export class ContextCompactor {
+    config;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Estimate the token count for a list of messages using the 4-chars-per-token
+     * heuristic.
+     */
+    estimateTokens(messages) {
+        let totalChars = 0;
+        for (const msg of messages) {
+            totalChars += messageToText(msg).length;
+            // Add a small overhead per message for role + formatting
+            totalChars += 10;
+        }
+        return Math.ceil(totalChars / CHARS_PER_TOKEN);
+    }
+    /**
+     * 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.
+     */
+    async compact(messages, apiCall) {
+        if (this.config.useLLM && apiCall !== undefined) {
+            try {
+                return await this.compactWithLLM(messages, apiCall);
+            }
+            catch (err) {
+                console.error("[ContextCompactor] LLM compaction failed, falling back to local:", err);
+                // Fall through to local compaction below
+            }
+        }
+        return this._compactLocal(messages);
+    }
+    /**
+     * 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.
+     */
+    async compactWithLLM(messages, apiCall) {
+        const originalTokens = this.estimateTokens(messages);
+        if (originalTokens < this.config.compactionThreshold) {
+            return {
+                messages,
+                compacted: false,
+                originalTokens,
+                compactedTokens: originalTokens,
+                turnsCompacted: 0,
+            };
+        }
+        const systemMessages = messages.filter((m) => m.role === "system");
+        const conversational = messages.filter((m) => m.role !== "system");
+        const turnsToPreserve = this.config.preserveRecentTurns * 2;
+        const splitAt = Math.max(0, conversational.length - turnsToPreserve);
+        const toCompact = conversational.slice(0, splitAt);
+        const toPreserve = conversational.slice(splitAt);
+        const turnsCompacted = toCompact.length;
+        if (turnsCompacted === 0) {
+            return {
+                messages,
+                compacted: false,
+                originalTokens,
+                compactedTokens: originalTokens,
+                turnsCompacted: 0,
+            };
+        }
+        // Build a transcript of the messages to be compacted
+        const transcript = toCompact
+            .map((m) => {
+            const role = m.role.toUpperCase();
+            const text = messageToText(m);
+            return `[${role}]: ${text}`;
+        })
+            .join("\n\n");
+        const prompt = [
+            "Summarize this conversation concisely. Include:",
+            "- Key decisions made",
+            "- Files modified and why",
+            "- Tool results and outcomes",
+            "- Current task status",
+            "Keep it under 500 words.",
+            "",
+            "--- CONVERSATION START ---",
+            transcript,
+            "--- CONVERSATION END ---",
+        ].join("\n");
+        const llmSummary = await apiCall(prompt);
+        const summaryText = `# Conversation Summary (LLM-compacted context)\n\n${llmSummary}`;
+        const summaryMessage = {
+            role: "system",
+            content: summaryText,
+        };
+        const compactedMessages = [
+            ...systemMessages,
+            summaryMessage,
+            ...toPreserve,
+        ];
+        const compactedTokens = this.estimateTokens(compactedMessages);
+        return {
+            messages: compactedMessages,
+            compacted: true,
+            originalTokens,
+            compactedTokens,
+            turnsCompacted,
+        };
+    }
+    /** Local heuristic compaction (no LLM). */
+    _compactLocal(messages) {
+        const originalTokens = this.estimateTokens(messages);
+        if (originalTokens < this.config.compactionThreshold) {
+            return {
+                messages,
+                compacted: false,
+                originalTokens,
+                compactedTokens: originalTokens,
+                turnsCompacted: 0,
+            };
+        }
+        // Separate system messages (always kept verbatim at the front) from the
+        // conversational messages that can be compacted.
+        const systemMessages = messages.filter((m) => m.role === "system");
+        const conversational = messages.filter((m) => m.role !== "system");
+        // A "turn" is a contiguous user+assistant exchange. For simplicity we treat
+        // each individual message as one turn unit here; the preserve count is in
+        // terms of individual messages (not user+assistant pairs).
+        const turnsToPreserve = this.config.preserveRecentTurns * 2; // user + assistant per turn
+        const splitAt = Math.max(0, conversational.length - turnsToPreserve);
+        const toCompact = conversational.slice(0, splitAt);
+        const toPreserve = conversational.slice(splitAt);
+        const turnsCompacted = toCompact.length;
+        if (turnsCompacted === 0) {
+            // Nothing old enough to compact
+            return {
+                messages,
+                compacted: false,
+                originalTokens,
+                compactedTokens: originalTokens,
+                turnsCompacted: 0,
+            };
+        }
+        const summaryText = buildSummary(toCompact, this.config.summaryMaxTokens);
+        const summaryMessage = {
+            role: "system",
+            content: summaryText,
+        };
+        const compactedMessages = [
+            ...systemMessages,
+            summaryMessage,
+            ...toPreserve,
+        ];
+        const compactedTokens = this.estimateTokens(compactedMessages);
+        return {
+            messages: compactedMessages,
+            compacted: true,
+            originalTokens,
+            compactedTokens,
+            turnsCompacted,
+        };
+    }
+}
+//# sourceMappingURL=context-compactor.js.map

package/dist/agents/conversation-branch.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Conversation Branching
+ *
+ * Allows forking a conversation at any turn to explore alternative paths.
+ * Branches are persisted to .profclaw/branches/branches.json.
+ * The transcript for the parent conversation is read from the existing
+ * TranscriptStore (JSONL files at .profclaw/transcripts/).
+ */
+export interface Branch {
+    id: string;
+    parentId: string;
+    forkTurnIndex: number;
+    title?: string;
+    createdAt: number;
+}
+interface BranchMessage {
+    role: string;
+    content: string;
+}
+export declare class ConversationBrancher {
+    private branches;
+    private branchDir;
+    private transcriptStore;
+    constructor(projectRoot?: string);
+    /**
+     * Fork a conversation at a specific turn index.
+     * The new Branch records which turn we branched from so the caller
+     * can replay context up to that point.
+     */
+    fork(conversationId: string, turnIndex: number, title?: string): Branch;
+    /**
+     * List all branches whose parentId matches `conversationId`,
+     * sorted newest first.
+     */
+    listBranches(conversationId: string): Branch[];
+    /**
+     * Return the messages from the parent conversation up to (and including)
+     * `branch.forkTurnIndex`. Only user/assistant entries are included.
+     *
+     * "Turn" here means a user+assistant exchange pair, so turn N covers
+     * transcript entries 0..2N+1. We expose the raw forkTurnIndex as a
+     * transcript entry index for simplicity.
+     */
+    getBaseMessages(branch: Branch): BranchMessage[];
+    save(): void;
+    load(): void;
+    private ensureDir;
+    private indexPath;
+}
+/**
+ * Returns the shared singleton ConversationBrancher instance.
+ */
+export declare function getConversationBrancher(): ConversationBrancher;
+export {};
+//# sourceMappingURL=conversation-branch.d.ts.map