profclaw 2.0.0 → 2.4.0

package/dist/agents/prompt-suggestions.js

@@ -0,0 +1,208 @@
+/**
+ * PromptSuggestionEngine
+ *
+ * Generates contextual follow-up prompt suggestions based on the current
+ * conversation context. All logic is local — no LLM calls.
+ */
+// ── Helpers ───────────────────────────────────────────────────────────────────
+const CODE_PATTERNS = [
+    /```[\w]*\n/,
+    /function\s+\w+/,
+    /class\s+\w+/,
+    /const\s+\w+\s*=/,
+    /import\s+/,
+    /export\s+/,
+    /\.(ts|js|tsx|jsx|py|go|rs|java)\b/,
+    /\bcode\b/i,
+    /\bimplementation\b/i,
+    /\brefactor\b/i,
+];
+const ERROR_PATTERNS = [
+    /\berror\b/i,
+    /\bfailed\b/i,
+    /\bfailure\b/i,
+    /\bexception\b/i,
+    /\bthrew\b/i,
+    /\bcrash\b/i,
+    /\bundefined\b/i,
+    /\bnull\b/i,
+    /\btrace\b/i,
+    /\bstack\b/i,
+];
+const FILE_EDIT_PATTERNS = [
+    /\bedited\b/i,
+    /\bmodified\b/i,
+    /\bupdated\b/i,
+    /\bwrote\b/i,
+    /\bchanged\b/i,
+    /\bsaved\b/i,
+    /\bfile\b/i,
+];
+const CONCEPT_PATTERNS = [
+    /\bexplain\b/i,
+    /\bhow\s+does\b/i,
+    /\bwhat\s+is\b/i,
+    /\bwhy\b/i,
+    /\bwhen\s+should\b/i,
+    /\bdifference\b/i,
+];
+function containsAny(text, patterns) {
+    return patterns.some((p) => p.test(text));
+}
+/** Extract a plausible code subject from the assistant message (best-effort). */
+function extractCodeSubject(response) {
+    // Try to find a function/class name
+    const fnMatch = response.match(/function\s+(\w+)/);
+    if (fnMatch)
+        return fnMatch[1] ?? 'this';
+    const classMatch = response.match(/class\s+(\w+)/);
+    if (classMatch)
+        return classMatch[1] ?? 'this';
+    const constMatch = response.match(/const\s+(\w+)\s*=/);
+    if (constMatch)
+        return constMatch[1] ?? 'this';
+    return 'this';
+}
+/** Extract the first tool name from the list or a default. */
+function extractToolName(tools) {
+    return tools[0] ?? 'this tool';
+}
+// ── Engine ────────────────────────────────────────────────────────────────────
+export class PromptSuggestionEngine {
+    /**
+     * Generate up to 3 contextual follow-up suggestions.
+     *
+     * Rules (local, no LLM):
+     * - If assistant mentioned code → "Can you explain X?" or "Write tests for this"
+     * - If assistant used tools    → "What else can you do with {tool}?"
+     * - If short conversation      → exploratory prompts
+     * - If error was mentioned     → "How do I fix this?" or "What caused this?"
+     * - If file was edited         → "Show me the diff" or "Run the tests"
+     * - Vary by conversation length (early = broad, late = specific)
+     * - Always cap at 3
+     */
+    generateSuggestions(context) {
+        const { lastUserMessage, lastAssistantResponse, toolsUsed = [], conversationLength } = context;
+        const combined = lastUserMessage + ' ' + lastAssistantResponse;
+        const suggestions = [];
+        const hasCode = containsAny(combined, CODE_PATTERNS);
+        const hasError = containsAny(combined, ERROR_PATTERNS);
+        const hasFileEdit = containsAny(combined, FILE_EDIT_PATTERNS);
+        const hasTools = toolsUsed.length > 0;
+        const hasConcept = containsAny(combined, CONCEPT_PATTERNS);
+        const isEarlyConversation = conversationLength <= 4;
+        // --- Error-related suggestions (highest priority) ---
+        if (hasError) {
+            suggestions.push({
+                text: 'How do I fix this error?',
+                category: 'follow-up',
+            });
+            suggestions.push({
+                text: 'What caused this error and how can I prevent it?',
+                category: 'deeper',
+            });
+        }
+        // --- File edit suggestions ---
+        if (hasFileEdit && !hasError) {
+            suggestions.push({
+                text: '/diff',
+                category: 'action',
+            });
+            suggestions.push({
+                text: 'Run the tests to verify the changes',
+                category: 'action',
+            });
+        }
+        // --- Code-related suggestions ---
+        if (hasCode && !hasError) {
+            const subject = extractCodeSubject(lastAssistantResponse);
+            suggestions.push({
+                text: `Can you explain how ${subject} works?`,
+                category: 'deeper',
+            });
+            suggestions.push({
+                text: 'Write tests for this',
+                category: 'action',
+            });
+            if (conversationLength > 4) {
+                suggestions.push({
+                    text: 'Optimize this for performance',
+                    category: 'related',
+                });
+            }
+        }
+        // --- Tool usage suggestions ---
+        if (hasTools && !hasError) {
+            const toolName = extractToolName(toolsUsed);
+            suggestions.push({
+                text: `What else can you do with ${toolName}?`,
+                category: 'related',
+            });
+        }
+        // --- Concept / explanation suggestions ---
+        if (hasConcept && !hasError && !hasCode) {
+            suggestions.push({
+                text: 'Can you give me a concrete example?',
+                category: 'follow-up',
+            });
+            suggestions.push({
+                text: 'What are the trade-offs?',
+                category: 'deeper',
+            });
+        }
+        // --- Early conversation: broad exploratory prompts ---
+        if (isEarlyConversation && suggestions.length < 2) {
+            suggestions.push({
+                text: 'What else can you help me with?',
+                category: 'related',
+            });
+            suggestions.push({
+                text: 'Can you elaborate on that?',
+                category: 'follow-up',
+            });
+        }
+        // --- Late conversation: specific follow-up ---
+        if (!isEarlyConversation && suggestions.length < 2) {
+            suggestions.push({
+                text: 'Summarize what we have done so far',
+                category: 'follow-up',
+            });
+            suggestions.push({
+                text: 'What should we do next?',
+                category: 'action',
+            });
+        }
+        // --- Always ensure at least 2 sensible defaults ---
+        if (suggestions.length === 0) {
+            suggestions.push({
+                text: 'Tell me more about this',
+                category: 'follow-up',
+            });
+            suggestions.push({
+                text: 'How does this compare to alternatives?',
+                category: 'related',
+            });
+        }
+        // Cap at 3, deduplicate by text
+        const seen = new Set();
+        const unique = [];
+        for (const s of suggestions) {
+            if (!seen.has(s.text)) {
+                seen.add(s.text);
+                unique.push(s);
+            }
+            if (unique.length === 3)
+                break;
+        }
+        return unique;
+    }
+}
+// ── Singleton ─────────────────────────────────────────────────────────────────
+let _engine = null;
+export function getPromptSuggestionEngine() {
+    if (!_engine) {
+        _engine = new PromptSuggestionEngine();
+    }
+    return _engine;
+}
+//# sourceMappingURL=prompt-suggestions.js.map

package/dist/agents/rate-limit-monitor.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ */
+export interface RateLimitState {
+    provider: string;
+    model: string;
+    requestsUsed: number;
+    requestsLimit?: number;
+    tokensUsed: number;
+    tokensLimit?: number;
+    /** Unix timestamp (ms) when limits reset */
+    resetAt?: number;
+    warningLevel: 'none' | 'info' | 'warning' | 'critical';
+}
+export interface WarnResult {
+    warn: boolean;
+    message: string;
+    level: RateLimitState['warningLevel'];
+}
+export declare class RateLimitMonitor {
+    private states;
+    constructor();
+    /**
+     * 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: string, headers: Record<string, string>): void;
+    /** Get current rate limit state for a provider. */
+    getState(provider: string): RateLimitState | undefined;
+    /**
+     * Check whether the user should be warned about rate limit usage.
+     * Returns the highest-severity warning across requests and tokens.
+     */
+    shouldWarn(provider: string): WarnResult;
+    /**
+     * Suggest an alternative provider when the given provider is at a high usage level.
+     * Returns undefined if no switch is recommended.
+     */
+    suggestAlternative(provider: string, availableProviders: string[]): string | undefined;
+    /** Return a snapshot of all tracked provider states. */
+    getAll(): RateLimitState[];
+    private getOrCreate;
+}
+export declare function getRateLimitMonitor(): RateLimitMonitor;
+//# sourceMappingURL=rate-limit-monitor.d.ts.map

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/receipt/receipt-cli.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Helpers that connect receipts to the CLI: key handling and writer setup.
+ */
+import { ReceiptWriter } from './receipt-writer.js';
+export interface RunReceiptArgs {
+    projectRoot: string;
+    runId: string;
+    /** --sign-key path; falls back to env PROFCLAW_RECEIPT_KEY */
+    signKeyPath?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/** Create the writer for a run. Signing is off unless a key path is given. */
+export declare function createRunReceipt(args: RunReceiptArgs): ReceiptWriter;
+/** Version of the running profclaw package, or 'unknown'. */
+export declare function toolVersion(): string;
+export interface KeyPairFiles {
+    privateKeyPath: string;
+    publicKeyPath: string;
+}
+/** Write an Ed25519 keypair into dir. The private key file is mode 0600. */
+export declare function generateKeyPairFiles(dir: string): KeyPairFiles;
+/** Short one-line description of tool arguments. Long values are cut so files are not copied into the receipt. */
+export declare function summarizeArgs(args: Record<string, unknown>, maxChars?: number): string;
+export interface RunReceiptSetup {
+    runId: string;
+    receipt?: ReceiptWriter;
+    /** Hook for ExecutorRunner: records each tool call */
+    onToolCall?: (event: {
+        attempt: number;
+        name: string;
+        args: Record<string, unknown>;
+        durationMs: number;
+        ok: boolean;
+    }) => void;
+}
+/** Everything `profclaw run` needs to record a receipt; a no-op setup when disabled. */
+export declare function setupRunReceipt(args: {
+    enabled: boolean;
+    projectRoot: string;
+    signKeyPath?: string;
+    env?: NodeJS.ProcessEnv;
+}): RunReceiptSetup;
+//# sourceMappingURL=receipt-cli.d.ts.map

package/dist/agents/receipt/receipt-cli.js

@@ -0,0 +1,82 @@
+/**
+ * Helpers that connect receipts to the CLI: key handling and writer setup.
+ */
+import { createRequire } from 'node:module';
+import { generateKeyPairSync } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { ReceiptWriter, defaultReceiptPath, loadSignerFromFile } from './receipt-writer.js';
+/** Create the writer for a run. Signing is off unless a key path is given. */
+export function createRunReceipt(args) {
+    const env = args.env ?? process.env;
+    const keyPath = args.signKeyPath ?? (env['PROFCLAW_RECEIPT_KEY']?.trim() || undefined);
+    return new ReceiptWriter({
+        path: defaultReceiptPath(args.projectRoot, args.runId, env),
+        signer: keyPath ? loadSignerFromFile(keyPath) : undefined,
+    });
+}
+/** Version of the running profclaw package, or 'unknown'. */
+export function toolVersion() {
+    try {
+        const pkg = createRequire(import.meta.url)('../../../package.json');
+        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Write an Ed25519 keypair into dir. The private key file is mode 0600. */
+export function generateKeyPairFiles(dir) {
+    mkdirSync(dir, { recursive: true });
+    const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+    const privateKeyPath = join(dir, 'receipt-key.pem');
+    const publicKeyPath = join(dir, 'receipt-key.pub.pem');
+    writeFileSync(privateKeyPath, privateKey.export({ type: 'pkcs8', format: 'pem' }), { mode: 0o600, flag: 'wx' });
+    writeFileSync(publicKeyPath, publicKey.export({ type: 'spki', format: 'pem' }), { mode: 0o644, flag: 'wx' });
+    return { privateKeyPath, publicKeyPath };
+}
+function argsSummaryChars(env) {
+    const n = Number(env['PROFCLAW_RECEIPT_ARGS_CHARS']);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 300;
+}
+/** Short one-line description of tool arguments. Long values are cut so files are not copied into the receipt. */
+export function summarizeArgs(args, maxChars = 300) {
+    const perValue = Math.max(16, Math.floor(maxChars / 3));
+    const parts = Object.entries(args).map(([key, value]) => {
+        const text = typeof value === 'string' ? value : JSON.stringify(value) ?? 'undefined';
+        const short = text.length > perValue ? `${text.slice(0, perValue)}...(${text.length} chars)` : text;
+        return `${key}=${JSON.stringify(short)}`;
+    });
+    const joined = parts.join(' ');
+    return joined.length > maxChars ? `${joined.slice(0, maxChars)}...` : joined;
+}
+/** Everything `profclaw run` needs to record a receipt; a no-op setup when disabled. */
+export function setupRunReceipt(args) {
+    const runId = randomUUID().slice(0, 8);
+    if (!args.enabled)
+        return { runId };
+    const env = args.env ?? process.env;
+    const receipt = createRunReceipt({ projectRoot: args.projectRoot, runId, signKeyPath: args.signKeyPath, env });
+    const cap = argsSummaryChars(env);
+    return {
+        runId,
+        receipt,
+        onToolCall: (e) => {
+            try {
+                receipt.append('tool_call', {
+                    attempt: e.attempt,
+                    name: e.name,
+                    argsSummary: summarizeArgs(e.args, cap),
+                    redacted: false,
+                    durationMs: e.durationMs,
+                    ok: e.ok,
+                });
+            }
+            catch {
+                // Receipt problems must never break the agent; a missing event shows up as a bad chain or gap.
+            }
+        },
+    };
+}
+//# sourceMappingURL=receipt-cli.js.map