profclaw 2.0.0 → 2.3.0

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

package/dist/agents/conversation-branch.js

@@ -0,0 +1,115 @@
+/**
+ * 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/).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { randomUUID } from 'crypto';
+import { TranscriptStore } from './transcript.js';
+// ── Singleton ─────────────────────────────────────────────────────────────────
+let _instance = null;
+// ── Class ─────────────────────────────────────────────────────────────────────
+export class ConversationBrancher {
+    branches;
+    branchDir;
+    transcriptStore;
+    constructor(projectRoot) {
+        const root = projectRoot ?? process.cwd();
+        this.branchDir = path.join(root, '.profclaw', 'branches');
+        this.branches = new Map();
+        this.transcriptStore = new TranscriptStore(root);
+        this.load();
+    }
+    // ── Public API ──────────────────────────────────────────────────────────────
+    /**
+     * 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, turnIndex, title) {
+        const branch = {
+            id: randomUUID(),
+            parentId: conversationId,
+            forkTurnIndex: turnIndex,
+            title,
+            createdAt: Date.now(),
+        };
+        this.branches.set(branch.id, branch);
+        this.save();
+        return branch;
+    }
+    /**
+     * List all branches whose parentId matches `conversationId`,
+     * sorted newest first.
+     */
+    listBranches(conversationId) {
+        return Array.from(this.branches.values())
+            .filter(b => b.parentId === conversationId)
+            .sort((a, b) => b.createdAt - a.createdAt);
+    }
+    /**
+     * 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) {
+        const entries = this.transcriptStore.getSession(branch.parentId);
+        const conversationEntries = entries.filter(e => e.type === 'user' || e.type === 'assistant');
+        const sliced = conversationEntries.slice(0, branch.forkTurnIndex + 1);
+        return sliced.map(e => ({
+            role: e.type === 'user' ? 'user' : 'assistant',
+            content: e.content,
+        }));
+    }
+    // ── Persistence ─────────────────────────────────────────────────────────────
+    save() {
+        this.ensureDir();
+        const filePath = this.indexPath();
+        const data = Array.from(this.branches.values());
+        try {
+            fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
+        }
+        catch (err) {
+            console.error('[ConversationBrancher] Failed to save branches:', err);
+        }
+    }
+    load() {
+        const filePath = this.indexPath();
+        if (!fs.existsSync(filePath))
+            return;
+        try {
+            const raw = fs.readFileSync(filePath, 'utf8');
+            const data = JSON.parse(raw);
+            this.branches = new Map(data.map(b => [b.id, b]));
+        }
+        catch (err) {
+            console.error('[ConversationBrancher] Failed to load branches:', err);
+        }
+    }
+    // ── Private helpers ─────────────────────────────────────────────────────────
+    ensureDir() {
+        if (!fs.existsSync(this.branchDir)) {
+            fs.mkdirSync(this.branchDir, { recursive: true });
+        }
+    }
+    indexPath() {
+        return path.join(this.branchDir, 'branches.json');
+    }
+}
+/**
+ * Returns the shared singleton ConversationBrancher instance.
+ */
+export function getConversationBrancher() {
+    if (!_instance) {
+        _instance = new ConversationBrancher();
+    }
+    return _instance;
+}
+//# sourceMappingURL=conversation-branch.js.map

package/dist/agents/error-recovery.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Error Recovery Advisor
+ *
+ * Analyzes API errors and returns an ordered list of recovery actions.
+ * The caller drives the actual recovery; this module is purely advisory.
+ */
+export interface RecoveryAction {
+    type: 'retry' | 'switch_provider' | 'switch_model' | 'reduce_context' | 'wait' | 'abort';
+    description: string;
+    provider?: string;
+    model?: string;
+    waitMs?: number;
+}
+export interface ErrorInput {
+    code?: string;
+    message: string;
+    provider: string;
+    model: string;
+    statusCode?: number;
+}
+export interface RecoveryContext {
+    availableProviders: string[];
+    retryCount: number;
+    maxRetries: number;
+}
+export declare class ErrorRecoveryAdvisor {
+    /**
+     * Analyze an error and return an ordered list of recommended recovery actions.
+     *
+     * Rules applied (in priority order):
+     *   401 / 403 → abort (auth errors cannot be retried)
+     *   429 (rate limit) → wait + switch_provider (if available) + retry
+     *   503 (server overloaded) → wait + retry
+     *   400 (bad request) → reduce_context or switch_model
+     *   ECONNREFUSED / ENOTFOUND → switch_provider
+     *   timeout → wait briefly + retry with reduce_context hint
+     *   context_length_exceeded → reduce_context + switch_model
+     *   content filter → switch_model
+     *   generic retry-eligible → retry (up to maxRetries)
+     */
+    advise(error: ErrorInput, context: RecoveryContext): RecoveryAction[];
+}
+export declare function getErrorRecoveryAdvisor(): ErrorRecoveryAdvisor;
+//# sourceMappingURL=error-recovery.d.ts.map