profclaw 2.0.0 → 2.3.0

package/dist/agents/rate-limit-monitor.js

@@ -0,0 +1,224 @@
+/**
+ * Rate Limit Monitor
+ *
+ * Tracks API rate limit state per provider by parsing standard x-ratelimit-*
+ * response headers. Surfaces warnings when usage thresholds are reached and
+ * can suggest alternative providers when limits are critical.
+ */
+// === Constants ===
+const THRESHOLD_INFO = 0.75;
+const THRESHOLD_WARNING = 0.90;
+const THRESHOLD_CRITICAL = 0.95;
+// Provider preference order for suggesting alternatives (prefer local)
+const PROVIDER_PREFERENCE = ['ollama', 'anthropic', 'openai', 'azure', 'google', 'cerebras'];
+function defaultState(provider) {
+    return {
+        provider,
+        model: 'unknown',
+        requestsUsed: 0,
+        tokensUsed: 0,
+        warningLevel: 'none',
+    };
+}
+/**
+ * Parse a reset timestamp header value.
+ * Accepts either a Unix timestamp (seconds) or a relative duration like "1m30s".
+ */
+function parseResetHeader(value) {
+    const trimmed = value.trim();
+    // ISO 8601 / epoch seconds (pure number)
+    const asNumber = Number(trimmed);
+    if (!isNaN(asNumber) && asNumber > 0) {
+        // If it looks like seconds since epoch (> year 2000), treat as epoch seconds
+        if (asNumber > 1_000_000_000) {
+            return asNumber * 1000; // convert to ms
+        }
+        // Otherwise treat as seconds from now
+        return Date.now() + asNumber * 1000;
+    }
+    // Relative duration: e.g. "1m30s", "45s", "2m"
+    const durationMatch = trimmed.match(/^(?:(\d+)m)?(?:(\d+(?:\.\d+)?)s)?$/);
+    if (durationMatch) {
+        const minutes = parseInt(durationMatch[1] ?? '0', 10);
+        const seconds = parseFloat(durationMatch[2] ?? '0');
+        const totalMs = (minutes * 60 + seconds) * 1000;
+        if (totalMs > 0) {
+            return Date.now() + totalMs;
+        }
+    }
+    return undefined;
+}
+function computeWarningLevel(used, limit) {
+    const ratio = used / limit;
+    if (ratio >= THRESHOLD_CRITICAL)
+        return 'critical';
+    if (ratio >= THRESHOLD_WARNING)
+        return 'warning';
+    if (ratio >= THRESHOLD_INFO)
+        return 'info';
+    return 'none';
+}
+// === RateLimitMonitor ===
+export class RateLimitMonitor {
+    states;
+    constructor() {
+        this.states = new Map();
+    }
+    /**
+     * Update rate limit state from API response headers.
+     * Parses the standard x-ratelimit-* header set used by OpenAI-compatible APIs
+     * and Anthropic:
+     *   x-ratelimit-limit-requests
+     *   x-ratelimit-remaining-requests
+     *   x-ratelimit-limit-tokens
+     *   x-ratelimit-remaining-tokens
+     *   x-ratelimit-reset-requests
+     *   x-ratelimit-reset-tokens
+     */
+    updateFromHeaders(provider, headers) {
+        const state = this.getOrCreate(provider);
+        const limitRequests = headers['x-ratelimit-limit-requests'];
+        const remainingRequests = headers['x-ratelimit-remaining-requests'];
+        const limitTokens = headers['x-ratelimit-limit-tokens'];
+        const remainingTokens = headers['x-ratelimit-remaining-tokens'];
+        const resetRequests = headers['x-ratelimit-reset-requests'];
+        const resetTokens = headers['x-ratelimit-reset-tokens'];
+        if (limitRequests !== undefined) {
+            state.requestsLimit = parseInt(limitRequests, 10);
+        }
+        if (remainingRequests !== undefined && state.requestsLimit !== undefined) {
+            const remaining = parseInt(remainingRequests, 10);
+            state.requestsUsed = state.requestsLimit - remaining;
+        }
+        if (limitTokens !== undefined) {
+            state.tokensLimit = parseInt(limitTokens, 10);
+        }
+        if (remainingTokens !== undefined && state.tokensLimit !== undefined) {
+            const remaining = parseInt(remainingTokens, 10);
+            state.tokensUsed = state.tokensLimit - remaining;
+        }
+        // Pick the earliest reset timestamp if both are present
+        const resetMs = [resetRequests, resetTokens]
+            .filter((v) => v !== undefined)
+            .map(parseResetHeader)
+            .filter((v) => v !== undefined)
+            .sort((a, b) => a - b)[0];
+        if (resetMs !== undefined) {
+            state.resetAt = resetMs;
+        }
+        // Recalculate warning level — use whichever ratio is higher
+        let highestLevel = 'none';
+        if (state.requestsLimit && state.requestsLimit > 0) {
+            const reqLevel = computeWarningLevel(state.requestsUsed, state.requestsLimit);
+            if (levelIndex(reqLevel) > levelIndex(highestLevel)) {
+                highestLevel = reqLevel;
+            }
+        }
+        if (state.tokensLimit && state.tokensLimit > 0) {
+            const tokLevel = computeWarningLevel(state.tokensUsed, state.tokensLimit);
+            if (levelIndex(tokLevel) > levelIndex(highestLevel)) {
+                highestLevel = tokLevel;
+            }
+        }
+        state.warningLevel = highestLevel;
+    }
+    /** Get current rate limit state for a provider. */
+    getState(provider) {
+        return this.states.get(provider);
+    }
+    /**
+     * Check whether the user should be warned about rate limit usage.
+     * Returns the highest-severity warning across requests and tokens.
+     */
+    shouldWarn(provider) {
+        const state = this.states.get(provider);
+        if (!state || state.warningLevel === 'none') {
+            return { warn: false, message: '', level: 'none' };
+        }
+        const parts = [];
+        if (state.requestsLimit && state.requestsLimit > 0) {
+            const pct = Math.round((state.requestsUsed / state.requestsLimit) * 100);
+            parts.push(`${pct}% of request quota used`);
+        }
+        if (state.tokensLimit && state.tokensLimit > 0) {
+            const pct = Math.round((state.tokensUsed / state.tokensLimit) * 100);
+            parts.push(`${pct}% of token quota used`);
+        }
+        let resetNote = '';
+        if (state.resetAt) {
+            const remainMs = state.resetAt - Date.now();
+            if (remainMs > 0) {
+                const remainSec = Math.ceil(remainMs / 1000);
+                const mins = Math.floor(remainSec / 60);
+                const secs = remainSec % 60;
+                resetNote = mins > 0
+                    ? ` (resets in ${mins}m ${secs}s)`
+                    : ` (resets in ${secs}s)`;
+            }
+        }
+        const prefix = state.warningLevel === 'critical'
+            ? 'Rate limit critical'
+            : state.warningLevel === 'warning'
+                ? 'Approaching rate limit'
+                : 'Rate limit notice';
+        const message = `${prefix} [${provider}]: ${parts.join(', ')}${resetNote}`;
+        return {
+            warn: true,
+            message,
+            level: state.warningLevel,
+        };
+    }
+    /**
+     * Suggest an alternative provider when the given provider is at a high usage level.
+     * Returns undefined if no switch is recommended.
+     */
+    suggestAlternative(provider, availableProviders) {
+        const state = this.states.get(provider);
+        if (!state || levelIndex(state.warningLevel) < levelIndex('warning')) {
+            return undefined;
+        }
+        // Find a provider with no warning or lower warning level
+        const candidates = availableProviders
+            .filter(p => p !== provider)
+            .sort((a, b) => {
+            // Prefer low-warning providers first, then follow preference order
+            const aLevel = levelIndex(this.states.get(a)?.warningLevel ?? 'none');
+            const bLevel = levelIndex(this.states.get(b)?.warningLevel ?? 'none');
+            if (aLevel !== bLevel)
+                return aLevel - bLevel;
+            return PROVIDER_PREFERENCE.indexOf(a) - PROVIDER_PREFERENCE.indexOf(b);
+        });
+        return candidates[0];
+    }
+    /** Return a snapshot of all tracked provider states. */
+    getAll() {
+        return Array.from(this.states.values()).map(s => ({ ...s }));
+    }
+    // Private helpers
+    getOrCreate(provider) {
+        let state = this.states.get(provider);
+        if (!state) {
+            state = defaultState(provider);
+            this.states.set(provider, state);
+        }
+        return state;
+    }
+}
+// Numeric ordering of warning levels (for comparison)
+function levelIndex(level) {
+    switch (level) {
+        case 'none': return 0;
+        case 'info': return 1;
+        case 'warning': return 2;
+        case 'critical': return 3;
+    }
+}
+// === Singleton ===
+let _monitor;
+export function getRateLimitMonitor() {
+    if (!_monitor) {
+        _monitor = new RateLimitMonitor();
+    }
+    return _monitor;
+}
+//# sourceMappingURL=rate-limit-monitor.js.map

package/dist/agents/result-store.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Result Store
+ *
+ * Manages large tool results by spilling them to disk when they exceed the
+ * inline size limit. This prevents context windows from being flooded by
+ * large tool outputs (e.g. file reads, API dumps).
+ */
+export interface StoredResult {
+    /** Summary string (or full result if small enough) that goes into context */
+    inline: string;
+    /** Path to the temp file containing the full result, if spilled */
+    fullPath?: string;
+    /** Original serialized byte length */
+    originalSize: number;
+    /** Whether the stored content was truncated */
+    truncated: boolean;
+}
+export declare class ResultStore {
+    private results;
+    private tempDir;
+    constructor(sessionId: string);
+    /**
+     * Store a tool result. Small results stay inline; large results spill to
+     * disk and return a summary pointing to the temp file.
+     */
+    store(toolCallId: string, result: unknown): Promise<StoredResult>;
+    /**
+     * Retrieve a previously stored result by its tool call ID.
+     */
+    retrieve(toolCallId: string): StoredResult | undefined;
+    /**
+     * Delete all temp files created during this session.
+     */
+    cleanup(): Promise<void>;
+    private writeTempFile;
+}
+//# sourceMappingURL=result-store.d.ts.map

package/dist/agents/result-store.js

@@ -0,0 +1,104 @@
+/**
+ * Result Store
+ *
+ * Manages large tool results by spilling them to disk when they exceed the
+ * inline size limit. This prevents context windows from being flooded by
+ * large tool outputs (e.g. file reads, API dumps).
+ */
+import { writeFile, unlink, mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { logger } from "../utils/logger.js";
+/** Results <= 50KB stay inline in the context window */
+const MAX_INLINE_SIZE = 50_000;
+/** Results > 5MB get truncated before saving */
+const MAX_TOTAL_SIZE = 5_000_000;
+/** Number of chars to include in the inline preview */
+const PREVIEW_LENGTH = 500;
+export class ResultStore {
+    results = new Map();
+    tempDir;
+    constructor(sessionId) {
+        this.tempDir = join(tmpdir(), `profclaw-results-${sessionId}`);
+    }
+    /**
+     * Store a tool result. Small results stay inline; large results spill to
+     * disk and return a summary pointing to the temp file.
+     */
+    async store(toolCallId, result) {
+        const serialized = JSON.stringify(result);
+        const size = Buffer.byteLength(serialized, "utf8");
+        let stored;
+        if (size <= MAX_INLINE_SIZE) {
+            // Small enough — keep it in context as-is
+            stored = {
+                inline: serialized,
+                originalSize: size,
+                truncated: false,
+            };
+        }
+        else {
+            // Needs to spill to disk
+            const truncated = size > MAX_TOTAL_SIZE;
+            const content = truncated
+                ? serialized.slice(0, MAX_TOTAL_SIZE)
+                : serialized;
+            const filePath = await this.writeTempFile(toolCallId, content);
+            const preview = serialized.slice(0, PREVIEW_LENGTH);
+            const sizeLabel = truncated
+                ? `${MAX_TOTAL_SIZE.toLocaleString()} bytes (truncated from ${size.toLocaleString()} bytes)`
+                : `${size.toLocaleString()} bytes`;
+            stored = {
+                inline: `[Result stored: ${sizeLabel}. Use retrieve_result tool to access full data. Preview: ${preview}...]`,
+                fullPath: filePath,
+                originalSize: size,
+                truncated,
+            };
+            logger.debug("[ResultStore] Spilled large result to disk", {
+                toolCallId,
+                size,
+                truncated,
+                filePath,
+            });
+        }
+        this.results.set(toolCallId, stored);
+        return stored;
+    }
+    /**
+     * Retrieve a previously stored result by its tool call ID.
+     */
+    retrieve(toolCallId) {
+        return this.results.get(toolCallId);
+    }
+    /**
+     * Delete all temp files created during this session.
+     */
+    async cleanup() {
+        const deletions = [];
+        for (const [id, stored] of this.results.entries()) {
+            if (stored.fullPath) {
+                deletions.push(unlink(stored.fullPath).catch((err) => {
+                    logger.warn("[ResultStore] Failed to delete temp file", {
+                        id,
+                        path: stored.fullPath,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }));
+            }
+        }
+        await Promise.all(deletions);
+        this.results.clear();
+        logger.debug("[ResultStore] Cleaned up temp files", {
+            count: deletions.length,
+        });
+    }
+    async writeTempFile(toolCallId, content) {
+        await mkdir(this.tempDir, { recursive: true });
+        const fileName = `${toolCallId}-${randomUUID()}.json`;
+        const filePath = join(this.tempDir, fileName);
+        await writeFile(filePath, content, "utf8");
+        return filePath;
+    }
+}
+//# sourceMappingURL=result-store.js.map

package/dist/agents/session-diff.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Session Diff Tracker
+ *
+ * Records original file contents before the agent makes any edits so that
+ * a unified diff of all changes can be produced at any time (e.g. /diff).
+ */
+export type FileChangeStatus = 'modified' | 'created' | 'deleted';
+export declare class SessionDiffTracker {
+    private originals;
+    constructor();
+    /**
+     * Record the original content of a file before the agent touches it.
+     * Only the first call per file path is honoured — subsequent calls are
+     * ignored so the "before" state remains the pre-session state.
+     */
+    recordOriginal(filePath: string, content: string): void;
+    /**
+     * Record that a file was created during this session (it did not exist before).
+     */
+    recordCreated(filePath: string): void;
+    /**
+     * Generate a unified diff for all modified files.
+     * Returns an empty string if nothing has changed.
+     */
+    generateDiff(): Promise<string>;
+    /**
+     * Return a list of changed files with their status.
+     */
+    getChangedFiles(): Array<{
+        path: string;
+        status: FileChangeStatus;
+    }>;
+    /**
+     * Generate a unified diff for a single file.
+     * Returns an empty string if the file content is unchanged.
+     */
+    getFileDiff(filePath: string): Promise<string>;
+}
+/**
+ * Returns the process-level singleton SessionDiffTracker.
+ */
+export declare function getSessionDiffTracker(): SessionDiffTracker;
+//# sourceMappingURL=session-diff.d.ts.map

package/dist/agents/session-diff.js

@@ -0,0 +1,258 @@
+/**
+ * Session Diff Tracker
+ *
+ * Records original file contents before the agent makes any edits so that
+ * a unified diff of all changes can be produced at any time (e.g. /diff).
+ */
+import fs from 'node:fs/promises';
+let defaultTracker = null;
+export class SessionDiffTracker {
+    originals;
+    constructor() {
+        this.originals = new Map();
+    }
+    /**
+     * Record the original content of a file before the agent touches it.
+     * Only the first call per file path is honoured — subsequent calls are
+     * ignored so the "before" state remains the pre-session state.
+     */
+    recordOriginal(filePath, content) {
+        if (!this.originals.has(filePath)) {
+            this.originals.set(filePath, { originalContent: content, created: false });
+        }
+    }
+    /**
+     * Record that a file was created during this session (it did not exist before).
+     */
+    recordCreated(filePath) {
+        if (!this.originals.has(filePath)) {
+            this.originals.set(filePath, { originalContent: null, created: true });
+        }
+    }
+    /**
+     * Generate a unified diff for all modified files.
+     * Returns an empty string if nothing has changed.
+     */
+    async generateDiff() {
+        const parts = [];
+        for (const filePath of this.originals.keys()) {
+            const diff = await this.getFileDiff(filePath);
+            if (diff) {
+                parts.push(diff);
+            }
+        }
+        return parts.join('\n');
+    }
+    /**
+     * Return a list of changed files with their status.
+     */
+    getChangedFiles() {
+        const result = [];
+        for (const [filePath, tracked] of this.originals.entries()) {
+            if (tracked.created) {
+                result.push({ path: filePath, status: 'created' });
+            }
+            else {
+                result.push({ path: filePath, status: 'modified' });
+            }
+        }
+        return result;
+    }
+    /**
+     * Generate a unified diff for a single file.
+     * Returns an empty string if the file content is unchanged.
+     */
+    async getFileDiff(filePath) {
+        const tracked = this.originals.get(filePath);
+        if (!tracked)
+            return '';
+        let currentContent;
+        try {
+            currentContent = await fs.readFile(filePath, 'utf-8');
+        }
+        catch {
+            currentContent = null;
+        }
+        const originalContent = tracked.originalContent ?? '';
+        const newContent = currentContent ?? '';
+        if (originalContent === newContent)
+            return '';
+        const aLabel = tracked.created ? '/dev/null' : `a/${filePath}`;
+        const bLabel = currentContent === null ? '/dev/null' : `b/${filePath}`;
+        return buildUnifiedDiff(aLabel, bLabel, originalContent, newContent);
+    }
+}
+/**
+ * Returns the process-level singleton SessionDiffTracker.
+ */
+export function getSessionDiffTracker() {
+    if (!defaultTracker) {
+        defaultTracker = new SessionDiffTracker();
+    }
+    return defaultTracker;
+}
+// ---------------------------------------------------------------------------
+// Minimal unified diff implementation (no external dependencies)
+// ---------------------------------------------------------------------------
+function buildUnifiedDiff(aLabel, bLabel, oldText, newText) {
+    const oldLines = oldText === '' ? [] : oldText.split('\n');
+    const newLines = newText === '' ? [] : newText.split('\n');
+    const hunks = computeHunks(oldLines, newLines);
+    if (hunks.length === 0)
+        return '';
+    const header = [`--- ${aLabel}`, `+++ ${bLabel}`];
+    const body = hunks.map(renderHunk);
+    return [...header, ...body].join('\n') + '\n';
+}
+const CONTEXT = 3;
+function computeHunks(oldLines, newLines) {
+    // Myers-style LCS diff
+    const edit = shortestEditScript(oldLines, newLines);
+    // Group edits into hunks with context
+    const hunks = [];
+    // Build flat edit list
+    const ops = [];
+    let oi = 0;
+    let ni = 0;
+    for (const [type, content] of edit) {
+        if (type === '=') {
+            ops.push({ type: '=', oldIdx: oi, newIdx: ni, content });
+            oi++;
+            ni++;
+        }
+        else if (type === '-') {
+            ops.push({ type: '-', oldIdx: oi, newIdx: ni, content });
+            oi++;
+        }
+        else {
+            ops.push({ type: '+', oldIdx: oi, newIdx: ni, content });
+            ni++;
+        }
+    }
+    // Find change ranges
+    const changeIndices = ops
+        .map((op, i) => (op.type !== '=' ? i : -1))
+        .filter((i) => i !== -1);
+    if (changeIndices.length === 0)
+        return [];
+    // Merge ranges with context into hunks
+    let start = Math.max(0, changeIndices[0] - CONTEXT);
+    let end = Math.min(ops.length - 1, changeIndices[0] + CONTEXT);
+    const ranges = [];
+    for (let k = 1; k < changeIndices.length; k++) {
+        const ci = changeIndices[k];
+        if (ci - CONTEXT <= end + 1) {
+            end = Math.min(ops.length - 1, ci + CONTEXT);
+        }
+        else {
+            ranges.push([start, end]);
+            start = Math.max(0, ci - CONTEXT);
+            end = Math.min(ops.length - 1, ci + CONTEXT);
+        }
+    }
+    ranges.push([start, end]);
+    for (const [s, e] of ranges) {
+        const slice = ops.slice(s, e + 1);
+        const oldStart = (slice.find((op) => op.type !== '+')?.oldIdx ?? 0) + 1;
+        const newStart = (slice.find((op) => op.type !== '-')?.newIdx ?? 0) + 1;
+        const oldCount = slice.filter((op) => op.type !== '+').length;
+        const newCount = slice.filter((op) => op.type !== '-').length;
+        const header = `@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`;
+        const lines = slice.map((op) => {
+            if (op.type === '=')
+                return ` ${op.content}`;
+            if (op.type === '-')
+                return `-${op.content}`;
+            return `+${op.content}`;
+        });
+        hunks.push({ header, lines });
+    }
+    return hunks;
+}
+function renderHunk(hunk) {
+    return [hunk.header, ...hunk.lines].join('\n');
+}
+/**
+ * Produce a minimal edit script using the Myers diff algorithm.
+ * Returns an array of [type, line] tuples where type is '+', '-', or '='.
+ */
+function shortestEditScript(oldLines, newLines) {
+    const n = oldLines.length;
+    const m = newLines.length;
+    const max = n + m;
+    if (max === 0)
+        return [];
+    // v[k] stores the furthest-reaching x position for diagonal k
+    const v = new Array(2 * max + 1).fill(0);
+    const trace = [];
+    outer: for (let d = 0; d <= max; d++) {
+        trace.push([...v]);
+        for (let k = -d; k <= d; k += 2) {
+            const ki = k + max;
+            let x;
+            if (k === -d || (k !== d && v[ki - 1] < v[ki + 1])) {
+                x = v[ki + 1];
+            }
+            else {
+                x = v[ki - 1] + 1;
+            }
+            let y = x - k;
+            while (x < n && y < m && oldLines[x] === newLines[y]) {
+                x++;
+                y++;
+            }
+            v[ki] = x;
+            if (x >= n && y >= m) {
+                break outer;
+            }
+        }
+    }
+    // Backtrack to reconstruct the edit path
+    const edits = [];
+    let x = n;
+    let y = m;
+    for (let d = trace.length - 1; d >= 0 && (x > 0 || y > 0); d--) {
+        const vPrev = trace[d];
+        const k = x - y;
+        const ki = k + max;
+        let prevK;
+        if (k === -d || (k !== d && vPrev[ki - 1] < vPrev[ki + 1])) {
+            prevK = k + 1;
+        }
+        else {
+            prevK = k - 1;
+        }
+        const prevX = vPrev[prevK + max];
+        const prevY = prevX - prevK;
+        while (x > prevX + 1 && y > prevY + 1) {
+            edits.unshift(['=', oldLines[x - 1]]);
+            x--;
+            y--;
+        }
+        if (d > 0) {
+            if (x > prevX && y > prevY) {
+                edits.unshift(['=', oldLines[x - 1]]);
+                x--;
+                y--;
+            }
+            else if (x > prevX) {
+                edits.unshift(['-', oldLines[x - 1]]);
+                x--;
+            }
+            else if (y > prevY) {
+                edits.unshift(['+', newLines[y - 1]]);
+                y--;
+            }
+        }
+    }
+    while (x > 0) {
+        edits.unshift(['-', oldLines[x - 1]]);
+        x--;
+    }
+    while (y > 0) {
+        edits.unshift(['+', newLines[y - 1]]);
+        y--;
+    }
+    return edits;
+}
+//# sourceMappingURL=session-diff.js.map