profclaw 2.0.0 → 2.3.0

package/dist/agents/plan-mode.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Plan Mode - Two-phase workflow for agent task planning and execution
+ *
+ * Provides plan storage and management. Plans are persisted to
+ * .profclaw/plans/{id}.json inside the project root (or home dir fallback).
+ */
+export interface PlanStep {
+    index: number;
+    description: string;
+    status: 'pending' | 'in_progress' | 'completed' | 'skipped';
+    files?: string[];
+    estimatedEffort?: 'small' | 'medium' | 'large';
+}
+export interface Plan {
+    id: string;
+    taskId?: string;
+    title: string;
+    steps: PlanStep[];
+    status: 'draft' | 'approved' | 'in_progress' | 'completed' | 'rejected';
+    rejectionReason?: string;
+    createdAt: number;
+    approvedAt?: number;
+    completedAt?: number;
+}
+export declare class PlanManager {
+    private plans;
+    private plansDir;
+    constructor(projectRoot?: string);
+    /** Load all persisted plans from disk into memory */
+    private _loadAll;
+    /**
+     * Create a new plan in draft status.
+     */
+    create(title: string, steps: Omit<PlanStep, 'status'>[]): Plan;
+    /**
+     * Approve a draft plan, transitioning it to in_progress.
+     */
+    approve(planId: string): Plan;
+    /**
+     * Reject a draft plan.
+     */
+    reject(planId: string, reason?: string): Plan;
+    /**
+     * Update the status of a specific step. Automatically marks the plan as
+     * completed when all steps are either completed or skipped.
+     */
+    updateStep(planId: string, stepIndex: number, status: PlanStep['status']): Plan;
+    /**
+     * Get a plan by ID. Returns undefined if not found.
+     */
+    get(planId: string): Plan | undefined;
+    /**
+     * Returns the currently active (in_progress) plan, if any.
+     */
+    getActive(): Plan | undefined;
+    /**
+     * Returns all plans, sorted newest first.
+     */
+    list(): Plan[];
+    /**
+     * Persist a plan to .profclaw/plans/{id}.json
+     */
+    save(plan: Plan): void;
+    /**
+     * Load a single plan from disk by ID.
+     */
+    load(planId: string): Plan | undefined;
+    private _getOrThrow;
+}
+export declare const planManager: PlanManager;
+//# sourceMappingURL=plan-mode.d.ts.map

package/dist/agents/plan-mode.js

@@ -0,0 +1,186 @@
+/**
+ * Plan Mode - Two-phase workflow for agent task planning and execution
+ *
+ * Provides plan storage and management. Plans are persisted to
+ * .profclaw/plans/{id}.json inside the project root (or home dir fallback).
+ */
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { logger } from '../utils/logger.js';
+// Helpers
+function resolvePlansDir(projectRoot) {
+    const base = projectRoot ?? process.cwd();
+    return join(base, '.profclaw', 'plans');
+}
+function ensureDir(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+// PlanManager
+export class PlanManager {
+    plans;
+    plansDir;
+    constructor(projectRoot) {
+        this.plans = new Map();
+        this.plansDir = resolvePlansDir(projectRoot ?? homedir());
+        this._loadAll();
+    }
+    /** Load all persisted plans from disk into memory */
+    _loadAll() {
+        try {
+            if (!existsSync(this.plansDir))
+                return;
+            const files = readdirSync(this.plansDir).filter((f) => f.endsWith('.json'));
+            for (const file of files) {
+                const planId = file.replace(/\.json$/, '');
+                const plan = this.load(planId);
+                if (plan) {
+                    this.plans.set(plan.id, plan);
+                }
+            }
+        }
+        catch (err) {
+            logger.warn('[PlanManager] Failed to load plans from disk:', { error: String(err) });
+        }
+    }
+    /**
+     * Create a new plan in draft status.
+     */
+    create(title, steps) {
+        const plan = {
+            id: randomUUID(),
+            title,
+            steps: steps.map((s) => ({ ...s, status: 'pending' })),
+            status: 'draft',
+            createdAt: Date.now(),
+        };
+        this.plans.set(plan.id, plan);
+        this.save(plan);
+        logger.info('[PlanManager] Plan created:', { id: plan.id, title, stepCount: steps.length });
+        return plan;
+    }
+    /**
+     * Approve a draft plan, transitioning it to in_progress.
+     */
+    approve(planId) {
+        const plan = this._getOrThrow(planId);
+        if (plan.status !== 'draft') {
+            throw new Error(`Plan ${planId} is not in draft status (current: ${plan.status})`);
+        }
+        const updated = {
+            ...plan,
+            status: 'in_progress',
+            approvedAt: Date.now(),
+        };
+        this.plans.set(planId, updated);
+        this.save(updated);
+        logger.info('[PlanManager] Plan approved:', { id: planId });
+        return updated;
+    }
+    /**
+     * Reject a draft plan.
+     */
+    reject(planId, reason) {
+        const plan = this._getOrThrow(planId);
+        if (plan.status !== 'draft') {
+            throw new Error(`Plan ${planId} is not in draft status (current: ${plan.status})`);
+        }
+        const updated = {
+            ...plan,
+            status: 'rejected',
+            rejectionReason: reason,
+        };
+        this.plans.set(planId, updated);
+        this.save(updated);
+        logger.info('[PlanManager] Plan rejected:', { id: planId, reason });
+        return updated;
+    }
+    /**
+     * Update the status of a specific step. Automatically marks the plan as
+     * completed when all steps are either completed or skipped.
+     */
+    updateStep(planId, stepIndex, status) {
+        const plan = this._getOrThrow(planId);
+        const stepIdx = plan.steps.findIndex((s) => s.index === stepIndex);
+        if (stepIdx === -1) {
+            throw new Error(`Step ${stepIndex} not found in plan ${planId}`);
+        }
+        const updatedSteps = plan.steps.map((s) => s.index === stepIndex ? { ...s, status } : s);
+        const allDone = updatedSteps.every((s) => s.status === 'completed' || s.status === 'skipped');
+        const updated = {
+            ...plan,
+            steps: updatedSteps,
+            status: allDone ? 'completed' : plan.status,
+            completedAt: allDone ? Date.now() : plan.completedAt,
+        };
+        this.plans.set(planId, updated);
+        this.save(updated);
+        return updated;
+    }
+    /**
+     * Get a plan by ID. Returns undefined if not found.
+     */
+    get(planId) {
+        return this.plans.get(planId);
+    }
+    /**
+     * Returns the currently active (in_progress) plan, if any.
+     */
+    getActive() {
+        for (const plan of this.plans.values()) {
+            if (plan.status === 'in_progress') {
+                return plan;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Returns all plans, sorted newest first.
+     */
+    list() {
+        return Array.from(this.plans.values()).sort((a, b) => b.createdAt - a.createdAt);
+    }
+    /**
+     * Persist a plan to .profclaw/plans/{id}.json
+     */
+    save(plan) {
+        try {
+            ensureDir(this.plansDir);
+            const filePath = join(this.plansDir, `${plan.id}.json`);
+            writeFileSync(filePath, JSON.stringify(plan, null, 2), 'utf-8');
+        }
+        catch (err) {
+            logger.error('[PlanManager] Failed to save plan:', err);
+        }
+    }
+    /**
+     * Load a single plan from disk by ID.
+     */
+    load(planId) {
+        try {
+            const filePath = join(this.plansDir, `${planId}.json`);
+            if (!existsSync(filePath))
+                return undefined;
+            const raw = readFileSync(filePath, 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch (err) {
+            logger.warn(`[PlanManager] Failed to load plan ${planId}:`, { error: String(err) });
+            return undefined;
+        }
+    }
+    // Private helpers
+    _getOrThrow(planId) {
+        const plan = this.plans.get(planId);
+        if (!plan) {
+            throw new Error(`Plan not found: ${planId}`);
+        }
+        return plan;
+    }
+}
+// Singleton instance used by tools and CLI commands
+export const planManager = new PlanManager();
+//# sourceMappingURL=plan-mode.js.map

package/dist/agents/prompt-suggestions.d.ts

@@ -0,0 +1,33 @@
+/**
+ * PromptSuggestionEngine
+ *
+ * Generates contextual follow-up prompt suggestions based on the current
+ * conversation context. All logic is local — no LLM calls.
+ */
+export interface Suggestion {
+    text: string;
+    category: 'follow-up' | 'deeper' | 'related' | 'action';
+}
+export interface SuggestionContext {
+    lastUserMessage: string;
+    lastAssistantResponse: string;
+    toolsUsed?: string[];
+    conversationLength: number;
+}
+export declare 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: SuggestionContext): Suggestion[];
+}
+export declare function getPromptSuggestionEngine(): PromptSuggestionEngine;
+//# sourceMappingURL=prompt-suggestions.d.ts.map

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