@yuaone/core 0.1.3 → 0.3.0

package/dist/prompt-defense.js

@@ -0,0 +1,311 @@
+/**
+ * Prompt Injection Defense Module
+ *
+ * Sanitizes tool outputs and user inputs to prevent prompt injection attacks.
+ * Standalone module — no internal imports.
+ */
+const INJECTION_PATTERNS = [
+    {
+        name: "ignore_previous_instructions",
+        regex: /ignore\s+previous\s+instructions/gi,
+        severity: "critical",
+    },
+    {
+        name: "ignore_all_instructions",
+        regex: /ignore\s+all\s+instructions/gi,
+        severity: "critical",
+    },
+    {
+        name: "disregard_directive",
+        regex: /disregard\s+(previous|all|above|system)/gi,
+        severity: "critical",
+    },
+    {
+        name: "identity_override",
+        regex: /you\s+are\s+now/gi,
+        severity: "high",
+    },
+    {
+        name: "new_instructions",
+        regex: /new\s+instructions\s*:/gi,
+        severity: "high",
+    },
+    {
+        name: "system_prompt_extraction",
+        regex: /system\s+prompt\s*:/gi,
+        severity: "critical",
+    },
+    {
+        name: "reveal_instructions",
+        regex: /reveal\s+your\s+(instructions|prompt|system)/gi,
+        severity: "critical",
+    },
+    {
+        name: "override_safety",
+        regex: /override\s+(safety|security|rules)/gi,
+        severity: "critical",
+    },
+    {
+        name: "jailbreak",
+        regex: /\bjailbreak\b/gi,
+        severity: "high",
+    },
+    {
+        name: "dan_mode",
+        regex: /\bDAN\s+mode\b/gi,
+        severity: "high",
+    },
+    {
+        name: "pretend_override",
+        regex: /pretend\s+you\s+are/gi,
+        severity: "medium",
+    },
+    {
+        name: "act_as_override",
+        regex: /act\s+as\s+if\s+you/gi,
+        severity: "medium",
+    },
+    {
+        name: "forget_everything",
+        regex: /forget\s+everything/gi,
+        severity: "high",
+    },
+    {
+        name: "prompt_format_system",
+        regex: /\[SYSTEM\]/gi,
+        severity: "high",
+    },
+    {
+        name: "prompt_format_inst",
+        regex: /\[INST\]/gi,
+        severity: "high",
+    },
+    {
+        name: "prompt_format_sys_tag",
+        regex: /<<SYS>>/gi,
+        severity: "high",
+    },
+];
+// ── Size limits per tool ────────────────────────────────────────────────────
+const TOOL_OUTPUT_LIMITS = {
+    file_read: 50_000,
+    grep: 20_000,
+    glob: 10_000,
+    shell_exec: 30_000,
+    git_ops: 20_000,
+    test_run: 30_000,
+    code_search: 20_000,
+};
+const DEFAULT_OUTPUT_LIMIT = 10_000;
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function getOutputLimit(toolName) {
+    return TOOL_OUTPUT_LIMITS[toolName] ?? DEFAULT_OUTPUT_LIMIT;
+}
+/**
+ * Attempt to decode base64 segments in a string and check for injections.
+ * Returns any injection matches found in decoded segments.
+ */
+function detectBase64Injections(text) {
+    const matches = [];
+    // Match potential base64 strings (at least 16 chars, valid base64 alphabet)
+    const b64Regex = /[A-Za-z0-9+/]{16,}={0,2}/g;
+    let b64Match;
+    while ((b64Match = b64Regex.exec(text)) !== null) {
+        let decoded;
+        try {
+            decoded = Buffer.from(b64Match[0], "base64").toString("utf-8");
+        }
+        catch {
+            continue;
+        }
+        // Check if the decoded string is mostly printable ASCII (sanity check)
+        const printable = decoded.replace(/[^\x20-\x7E]/g, "");
+        if (printable.length < decoded.length * 0.7) {
+            continue;
+        }
+        for (const pat of INJECTION_PATTERNS) {
+            const patRegex = new RegExp(pat.regex.source, pat.regex.flags);
+            const innerMatch = patRegex.exec(decoded);
+            if (innerMatch) {
+                matches.push({
+                    pattern: `base64:${pat.name}`,
+                    match: b64Match[0].substring(0, 40),
+                    position: b64Match.index,
+                });
+            }
+        }
+    }
+    return matches;
+}
+function severityRank(s) {
+    const ranks = {
+        none: 0,
+        low: 1,
+        medium: 2,
+        high: 3,
+        critical: 4,
+    };
+    return ranks[s];
+}
+function maxSeverity(a, b) {
+    return severityRank(a) >= severityRank(b) ? a : b;
+}
+function severityToRecommendation(severity) {
+    switch (severity) {
+        case "none":
+            return "allow";
+        case "low":
+        case "medium":
+            return "sanitize";
+        case "high":
+        case "critical":
+            return "block";
+    }
+}
+/**
+ * Filter characters for high-strictness mode.
+ * Removes non-printable control characters (except newline, tab, carriage return).
+ */
+function filterChars(text) {
+    // Keep printable ASCII, newline, tab, CR, and common unicode
+    // Strip control chars 0x00-0x08, 0x0B, 0x0C, 0x0E-0x1F, 0x7F
+    return text.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "");
+}
+// ── PromptDefense Class ─────────────────────────────────────────────────────
+export class PromptDefense {
+    defaultLevel;
+    constructor(defaultLevel = "medium") {
+        this.defaultLevel = defaultLevel;
+    }
+    /**
+     * Detect injection patterns in text, including base64-encoded variants.
+     */
+    detectInjection(text) {
+        const patterns = [];
+        let overallSeverity = "none";
+        // Direct pattern matching
+        for (const pat of INJECTION_PATTERNS) {
+            const regex = new RegExp(pat.regex.source, pat.regex.flags);
+            let m;
+            while ((m = regex.exec(text)) !== null) {
+                patterns.push({
+                    pattern: pat.name,
+                    match: m[0],
+                    position: m.index,
+                });
+                overallSeverity = maxSeverity(overallSeverity, pat.severity);
+            }
+        }
+        // Base64-encoded pattern matching
+        const b64Matches = detectBase64Injections(text);
+        for (const bm of b64Matches) {
+            patterns.push(bm);
+            // Base64-encoded injections are at least high severity (they imply intent)
+            overallSeverity = maxSeverity(overallSeverity, "high");
+        }
+        return {
+            detected: patterns.length > 0,
+            severity: overallSeverity,
+            patterns,
+            recommendation: severityToRecommendation(overallSeverity),
+        };
+    }
+    /**
+     * Sanitize a string: strip injection patterns, optionally truncate and filter.
+     */
+    sanitize(text, level) {
+        const effectiveLevel = level ?? this.defaultLevel;
+        let result = text;
+        // All levels: strip injection patterns
+        for (const pat of INJECTION_PATTERNS) {
+            result = result.replace(new RegExp(pat.regex.source, pat.regex.flags), "[REDACTED]");
+        }
+        // Medium+: also strip base64-encoded injections
+        if (effectiveLevel === "medium" || effectiveLevel === "high") {
+            const b64Regex = /[A-Za-z0-9+/]{16,}={0,2}/g;
+            const b64Segments = [];
+            let b64Match;
+            while ((b64Match = b64Regex.exec(result)) !== null) {
+                let decoded;
+                try {
+                    decoded = Buffer.from(b64Match[0], "base64").toString("utf-8");
+                }
+                catch {
+                    continue;
+                }
+                const printable = decoded.replace(/[^\x20-\x7E]/g, "");
+                if (printable.length < decoded.length * 0.7)
+                    continue;
+                for (const pat of INJECTION_PATTERNS) {
+                    if (new RegExp(pat.regex.source, pat.regex.flags).test(decoded)) {
+                        b64Segments.push({
+                            start: b64Match.index,
+                            end: b64Match.index + b64Match[0].length,
+                        });
+                        break;
+                    }
+                }
+            }
+            // Replace b64 segments in reverse order to preserve indices
+            for (let i = b64Segments.length - 1; i >= 0; i--) {
+                const seg = b64Segments[i];
+                result =
+                    result.substring(0, seg.start) +
+                        "[REDACTED:BASE64]" +
+                        result.substring(seg.end);
+            }
+        }
+        // High: aggressive character filtering
+        if (effectiveLevel === "high") {
+            result = filterChars(result);
+        }
+        return result;
+    }
+    /**
+     * Sanitize tool output: detect injections, strip patterns, truncate to limit.
+     */
+    sanitizeToolOutput(toolName, output) {
+        const originalLength = output.length;
+        const limit = getOutputLimit(toolName);
+        // Detect before sanitizing (for reporting)
+        const detection = this.detectInjection(output);
+        // Sanitize
+        let sanitized = this.sanitize(output, this.defaultLevel);
+        // Truncate
+        let truncated = false;
+        if (sanitized.length > limit) {
+            sanitized = sanitized.substring(0, limit) + "\n... [truncated]";
+            truncated = true;
+        }
+        return {
+            output: sanitized,
+            injectionDetected: detection.detected,
+            patternsFound: detection.patterns.map((p) => p.pattern),
+            truncated,
+            originalLength,
+        };
+    }
+    /**
+     * Validate user input for injection attempts.
+     */
+    validateUserInput(input) {
+        const detection = this.detectInjection(input);
+        const sanitizedInput = this.sanitize(input, this.defaultLevel);
+        return {
+            valid: !detection.detected || detection.severity === "low",
+            injectionDetected: detection.detected,
+            severity: detection.severity,
+            patternsFound: detection.patterns.map((p) => p.pattern),
+            sanitizedInput,
+        };
+    }
+    /**
+     * Wrap tool output with safety markers to prevent the LLM from confusing
+     * tool output with its own instructions.
+     */
+    wrapToolOutput(toolName, output) {
+        const result = this.sanitizeToolOutput(toolName, output);
+        return `[Tool Output: ${toolName}]\n${result.output}\n[End Tool Output]`;
+    }
+}
+//# sourceMappingURL=prompt-defense.js.map

package/dist/prompt-defense.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-defense.js","sourceRoot":"","sources":["../src/prompt-defense.ts"],"names":[],"mappings":"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"}

package/dist/reflexion.d.ts

@@ -0,0 +1,211 @@
+/**
+ * @module reflexion
+ * @description Reflexion Layer — structured self-reflection after each agent run.
+ *
+ * Based on the Reflexion paper (Shinn et al., 2023):
+ * dynamic memory + self-reflection loop for continuous improvement.
+ *
+ * Key design decisions:
+ * - `reflect()` is purely heuristic (no LLM calls) — analyzes tool results, counts failures, detects patterns
+ * - `getGuidance()` uses keyword matching to find relevant past reflections
+ * - Strategy confidence decays over time (0.95 per week)
+ * - File-based persistence in `.yuan/memory/`
+ * - Max 100 reflections (FIFO), max 50 strategies
+ *
+ * @example
+ * ```typescript
+ * const engine = new ReflexionEngine({ projectPath: "/my/project" });
+ *
+ * // After a run
+ * const entry = engine.reflect({ goal, runId, termination, toolResults, ... });
+ * await engine.store.saveReflection(entry);
+ *
+ * // Before a run
+ * const guidance = await engine.getGuidance("fix the auth middleware");
+ * const prompt = engine.formatForSystemPrompt(guidance);
+ * ```
+ */
+import type { Message, ToolResult, AgentTermination } from "./types.js";
+/** A single reflection entry from an agent run */
+export interface ReflexionEntry {
+    /** UUID */
+    id: string;
+    /** Agent run identifier */
+    runId: string;
+    /** Epoch ms */
+    timestamp: number;
+    /** Original user goal */
+    goal: string;
+    /** Run outcome */
+    outcome: "success" | "partial" | "failure";
+    /** From AgentTermination.reason */
+    terminationReason: string;
+    /** Self-reflection analysis */
+    reflection: {
+        /** Successful strategies */
+        whatWorked: string[];
+        /** Failed strategies */
+        whatFailed: string[];
+        /** Root cause of failure (if applicable) */
+        rootCause: string | null;
+        /** What to try next time */
+        alternativeApproach: string | null;
+    };
+    /** Tool usage analysis */
+    toolAnalysis: {
+        /** Which tools were called */
+        toolsUsed: string[];
+        /** Tools that failed */
+        failedTools: Array<{
+            tool: string;
+            error: string;
+            count: number;
+        }>;
+        /** Success rate 0–1 */
+        successRate: number;
+        /** Total tool calls */
+        totalCalls: number;
+        /** Average tool execution duration in ms */
+        avgDurationMs: number;
+    };
+    /** Run metrics */
+    metrics: {
+        iterations: number;
+        tokensUsed: number;
+        durationMs: number;
+        filesChanged: string[];
+    };
+}
+/** A learned strategy from successful runs */
+export interface StrategyRecord {
+    /** UUID */
+    id: string;
+    /** Regex or keyword pattern that matches similar tasks */
+    taskPattern: string;
+    /** Description of what works */
+    strategy: string;
+    /** Proven tool ordering */
+    toolSequence: string[];
+    /** Number of times this strategy succeeded */
+    successCount: number;
+    /** Number of times this strategy failed */
+    failureCount: number;
+    /** success / (success + failure) */
+    confidence: number;
+    /** Last used timestamp */
+    lastUsed: number;
+    /** Example goals that used this strategy */
+    examples: string[];
+}
+/** Guidance produced before an agent run */
+export interface ReflexionGuidance {
+    /** Relevant proven strategies */
+    relevantStrategies: StrategyRecord[];
+    /** Recent failures on similar tasks */
+    recentFailures: ReflexionEntry[];
+    /** Patterns that have failed before — things to avoid */
+    avoidPatterns: string[];
+    /** Suggested approach based on past success */
+    suggestedApproach: string | null;
+}
+/** Configuration for the ReflexionEngine */
+export interface ReflexionConfig {
+    /** Project root path — stores data in `.yuan/memory/` */
+    projectPath: string;
+    /** Maximum stored reflections (FIFO). Default 100 */
+    maxReflections?: number;
+    /** Maximum stored strategies. Default 50 */
+    maxStrategies?: number;
+    /** Confidence decay multiplier per week. Default 0.95 */
+    confidenceDecayPerWeek?: number;
+}
+/**
+ * File-based persistence for reflections and strategies.
+ *
+ * Storage location: `<projectPath>/.yuan/memory/`
+ */
+export declare class ReflexionStore {
+    private readonly memoryDir;
+    constructor(projectPath: string);
+    /** Save a reflection entry. Appends to the list. */
+    saveReflection(entry: ReflexionEntry): Promise<void>;
+    /** Get most recent reflections, optionally limited. */
+    getReflections(limit?: number): Promise<ReflexionEntry[]>;
+    /** Get reflections filtered by outcome. */
+    getReflectionsByOutcome(outcome: string): Promise<ReflexionEntry[]>;
+    /** Save or update a strategy record. */
+    saveStrategy(strategy: StrategyRecord): Promise<void>;
+    /** Find strategies relevant to a goal using keyword matching. */
+    findRelevantStrategies(goal: string, limit?: number): Promise<StrategyRecord[]>;
+    /** Update success/failure stats for a strategy. */
+    updateStrategyStats(strategyId: string, success: boolean): Promise<void>;
+    /** Remove reflections older than maxAge (ms). Returns count removed. */
+    pruneOldReflections(maxAge: number): Promise<number>;
+    private ensureDir;
+    private readJsonFile;
+    private writeJsonFile;
+    private loadReflectionsFile;
+    private loadStrategiesFile;
+}
+/** Parameters for the `reflect()` method */
+export interface ReflectParams {
+    goal: string;
+    runId: string;
+    termination: AgentTermination;
+    toolResults: ToolResult[];
+    messages: Message[];
+    tokensUsed: number;
+    durationMs: number;
+    changedFiles: string[];
+}
+/**
+ * ReflexionEngine — heuristic-based self-reflection after agent runs.
+ *
+ * No LLM calls. Analyzes tool results, detects failure patterns,
+ * extracts strategies from successful runs, and provides guidance
+ * for future runs.
+ */
+export declare class ReflexionEngine {
+    readonly store: ReflexionStore;
+    private readonly maxReflections;
+    private readonly maxStrategies;
+    private readonly confidenceDecayPerWeek;
+    constructor(config: ReflexionConfig);
+    /**
+     * After an agent run: analyze what happened and produce a ReflexionEntry.
+     *
+     * Purely heuristic — no LLM call. Analyzes:
+     * - Tool success/failure rates
+     * - Error patterns
+     * - Termination reason
+     * - Duration and resource usage
+     */
+    reflect(params: ReflectParams): ReflexionEntry;
+    /**
+     * Before an agent run: retrieve relevant past reflections for context injection.
+     *
+     * Searches reflections and strategies by keyword matching against the goal.
+     */
+    getGuidance(goal: string): Promise<ReflexionGuidance>;
+    /**
+     * Extract a StrategyRecord from a successful run.
+     *
+     * Only creates a strategy if the run used 3+ tool calls (nontrivial).
+     */
+    extractStrategy(entry: ReflexionEntry, goal: string): StrategyRecord | null;
+    /**
+     * Format guidance for injection into a system prompt.
+     *
+     * Returns empty string if no relevant guidance found.
+     */
+    formatForSystemPrompt(guidance: ReflexionGuidance): string;
+    /** Determine outcome from termination reason and tool results */
+    private determineOutcome;
+    /** Analyze tool usage from results */
+    private analyzeTools;
+    /** Build reflection heuristically from run data */
+    private buildReflection;
+    /** Apply time-based confidence decay to a strategy */
+    private applyConfidenceDecay;
+}
+//# sourceMappingURL=reflexion.d.ts.map

package/dist/reflexion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflexion.d.ts","sourceRoot":"","sources":["../src/reflexion.ts"],"names":[],"mappings":"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"}