@yuaone/core 0.9.7 → 0.9.9

package/dist/research-loop.js

@@ -0,0 +1,363 @@
+/**
+ * @module research-loop
+ * @description Hypothesis-driven engineering research loop.
+ *
+ * Takes a problem statement, generates hypotheses (template-based, no LLM),
+ * searches code/docs via a caller-supplied searchFn, evaluates evidence,
+ * and produces a strategy recommendation.
+ *
+ * Loop:
+ *   problem → hypotheses → search (code/docs) → evaluate evidence → update strategy
+ *
+ * Constraints:
+ * - ESM only (no require())
+ * - No LLM calls — purely structural, deterministic
+ * - Atomic writes (.tmp → renameSync)
+ * - All errors caught — never blocks
+ * - Emits agent:research_session_complete on completion
+ */
+import { EventEmitter } from "node:events";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Playbook name mapping from conclusion keywords */
+const STRATEGY_PLAYBOOK = [
+    { keywords: ["error", "fail", "crash", "exception", "throw"], strategy: "error-diagnosis-playbook" },
+    { keywords: ["import", "dependency", "module", "require", "resolve"], strategy: "dependency-resolution-playbook" },
+    { keywords: ["config", "configuration", "mismatch", "env", "environment"], strategy: "configuration-audit-playbook" },
+    { keywords: ["slow", "perf", "performance", "timeout", "latency", "bottleneck"], strategy: "performance-profiling-playbook" },
+    { keywords: ["algorithm", "inefficient", "complexity", "loop", "iteration"], strategy: "algorithm-optimization-playbook" },
+    { keywords: ["contention", "resource", "lock", "concurrency", "race"], strategy: "concurrency-analysis-playbook" },
+    { keywords: ["test", "assert", "logic", "contract", "expect"], strategy: "test-logic-review-playbook" },
+    { keywords: ["missing", "implement", "stub", "not found", "undefined"], strategy: "implementation-scaffold-playbook" },
+    { keywords: ["interface", "type", "signature", "mismatch", "incompatible"], strategy: "interface-alignment-playbook" },
+    { keywords: ["state", "corruption", "inconsistent", "mutation", "side effect"], strategy: "state-audit-playbook" },
+];
+const DEFAULT_STRATEGY = "general-investigation-playbook";
+const MAX_STORED_SESSIONS = 100;
+const SNIPPET_TRUNCATE = 300;
+const HYPOTHESIS_TEMPLATES = [
+    {
+        keywords: ["error", "fail", "crash", "exception", "throw", "broke"],
+        statements: [
+            "Root cause is a runtime error in the problem domain",
+            "Dependency or import is missing or incompatible",
+            "Configuration is mismatched between environments",
+        ],
+    },
+    {
+        keywords: ["slow", "perf", "performance", "timeout", "latency", "speed"],
+        statements: [
+            "Bottleneck exists in a hot code path",
+            "Algorithm or data structure choice is inefficient",
+            "Resource contention or blocking I/O is the limiting factor",
+        ],
+    },
+    {
+        keywords: ["test", "spec", "assert", "failing", "jest", "vitest", "mocha"],
+        statements: [
+            "Logic error exists in the implementation being tested",
+            "Test environment or setup is misconfigured",
+            "Contract between caller and implementation is violated",
+        ],
+    },
+];
+const DEFAULT_HYPOTHESES = [
+    "Required implementation is missing or incomplete",
+    "Interface or type contract is mismatched",
+    "State corruption or unexpected mutation is occurring",
+];
+function generateHypotheses(problem) {
+    const lower = problem.toLowerCase();
+    // Find first matching template
+    let statements = DEFAULT_HYPOTHESES;
+    for (const template of HYPOTHESIS_TEMPLATES) {
+        if (template.keywords.some((kw) => lower.includes(kw))) {
+            statements = template.statements;
+            break;
+        }
+    }
+    return statements.map((stmt) => ({
+        id: randomUUID(),
+        statement: stmt,
+        confidence: 0.3, // start with low prior
+        supportingEvidence: [],
+        contradictingEvidence: [],
+        status: "active",
+    }));
+}
+// ─── Query generation from hypothesis ────────────────────────────────────────
+function hypothesisToQuery(hypothesis, problem) {
+    // Extract the most specific noun phrases from hypothesis + first 6 words of problem
+    const problemWords = problem
+        .split(/\s+/)
+        .filter((w) => w.length > 3)
+        .slice(0, 6)
+        .join(" ");
+    return `${hypothesis.statement} ${problemWords}`.slice(0, 120);
+}
+// ─── Evidence evaluation ──────────────────────────────────────────────────────
+/** Extract keywords from a hypothesis statement (words >3 chars, no stopwords) */
+function hypothesisKeywords(statement) {
+    const STOPWORDS = new Set([
+        "root", "cause", "error", "code", "path", "that", "this", "from",
+        "into", "when", "where", "with", "have", "been", "will", "does",
+        "between", "missing", "existing", "problem", "domain",
+    ]);
+    return statement
+        .toLowerCase()
+        .split(/\W+/)
+        .filter((w) => w.length > 3 && !STOPWORDS.has(w));
+}
+/** Evaluate snippets against a hypothesis; update confidence and evidence */
+function evaluateEvidence(hypothesis, snippets, query) {
+    const keywords = hypothesisKeywords(hypothesis.statement);
+    const queryKeywords = query
+        .toLowerCase()
+        .split(/\W+/)
+        .filter((w) => w.length > 3)
+        .slice(0, 8);
+    const allKeywords = Array.from(new Set([...keywords, ...queryKeywords]));
+    for (const snippet of snippets) {
+        const lower = snippet.toLowerCase();
+        const hits = allKeywords.filter((kw) => lower.includes(kw)).length;
+        const hitRatio = allKeywords.length > 0 ? hits / allKeywords.length : 0;
+        if (hitRatio >= 0.25) {
+            // Supporting evidence: snippet contains ≥25% of keywords
+            const truncated = snippet.slice(0, SNIPPET_TRUNCATE);
+            if (!hypothesis.supportingEvidence.includes(truncated)) {
+                hypothesis.supportingEvidence.push(truncated);
+                hypothesis.confidence = Math.min(1.0, hypothesis.confidence + 0.2);
+            }
+        }
+        else if (hitRatio === 0 && snippet.length > 30) {
+            // Contradicting evidence: snippet is non-trivial but has no keyword overlap
+            const truncated = snippet.slice(0, SNIPPET_TRUNCATE);
+            if (hypothesis.contradictingEvidence.length < 3 &&
+                !hypothesis.contradictingEvidence.includes(truncated)) {
+                hypothesis.contradictingEvidence.push(truncated);
+                hypothesis.confidence = Math.max(0.0, hypothesis.confidence - 0.1);
+            }
+        }
+    }
+}
+// ─── Strategy selection from conclusion ──────────────────────────────────────
+function selectStrategy(conclusion) {
+    const lower = conclusion.toLowerCase();
+    for (const entry of STRATEGY_PLAYBOOK) {
+        if (entry.keywords.some((kw) => lower.includes(kw))) {
+            return entry.strategy;
+        }
+    }
+    return DEFAULT_STRATEGY;
+}
+// ─── Conclusion generation ────────────────────────────────────────────────────
+function buildConclusion(hypotheses) {
+    const sorted = [...hypotheses].sort((a, b) => b.confidence - a.confidence);
+    const top = sorted[0];
+    if (!top)
+        return "No hypothesis reached sufficient confidence.";
+    const evidence = top.supportingEvidence.length;
+    const contra = top.contradictingEvidence.length;
+    if (top.confidence >= 0.75) {
+        return `High confidence: ${top.statement}. Supported by ${evidence} evidence snippet(s), ${contra} contradicting.`;
+    }
+    else if (top.confidence >= 0.5) {
+        return `Moderate confidence: ${top.statement}. Supported by ${evidence} evidence snippet(s), ${contra} contradicting. Further investigation recommended.`;
+    }
+    else {
+        return `Low confidence (${(top.confidence * 100).toFixed(0)}%): ${top.statement}. Insufficient evidence found. Manual review required.`;
+    }
+}
+// ─── Storage helpers ──────────────────────────────────────────────────────────
+function defaultStorageDir() {
+    return join(homedir(), ".yuan", "research");
+}
+function sessionsFilePath(storageDir) {
+    return join(storageDir, "sessions.json");
+}
+function loadSessions(storageDir) {
+    const file = sessionsFilePath(storageDir);
+    if (!existsSync(file))
+        return [];
+    try {
+        const raw = readFileSync(file, "utf8");
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed.sessions) ? parsed.sessions : [];
+    }
+    catch {
+        return [];
+    }
+}
+function saveSessions(storageDir, sessions) {
+    try {
+        mkdirSync(storageDir, { recursive: true });
+        const capped = sessions.slice(-MAX_STORED_SESSIONS);
+        const file = sessionsFilePath(storageDir);
+        const tmp = file + ".tmp";
+        writeFileSync(tmp, JSON.stringify({ sessions: capped }, null, 2), "utf8");
+        renameSync(tmp, file);
+    }
+    catch {
+        // Non-fatal: storage failure should not crash the loop
+    }
+}
+// ─── Similarity helpers ───────────────────────────────────────────────────────
+/** Naive word-overlap similarity between two strings, 0..1 */
+function similarity(a, b) {
+    const wordsA = new Set(a.toLowerCase().split(/\W+/).filter((w) => w.length > 3));
+    const wordsB = new Set(b.toLowerCase().split(/\W+/).filter((w) => w.length > 3));
+    if (wordsA.size === 0 || wordsB.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const w of wordsA) {
+        if (wordsB.has(w))
+            intersection++;
+    }
+    return intersection / Math.max(wordsA.size, wordsB.size);
+}
+// ─── ResearchLoop ─────────────────────────────────────────────────────────────
+export class ResearchLoop extends EventEmitter {
+    maxIterations;
+    minConfidenceToStop;
+    storageDir;
+    sessions;
+    constructor(config = {}) {
+        super();
+        this.maxIterations = config.maxIterations ?? 5;
+        this.minConfidenceToStop = config.minConfidenceToStop ?? 0.75;
+        this.storageDir = config.storageDir ?? defaultStorageDir();
+        this.sessions = loadSessions(this.storageDir);
+    }
+    /**
+     * Run a hypothesis-driven research session for the given problem.
+     * - Generates 2-3 initial hypotheses (template-based, no LLM)
+     * - For each iteration, selects the lowest-confidence hypothesis, generates
+     *   a search query, calls searchFn for "code" and "docs", evaluates evidence
+     * - Stops early when minConfidenceToStop is reached
+     * - Returns completed ResearchSession with conclusion + recommendedStrategy
+     * - Emits agent:research_session_complete on completion
+     */
+    async research(problem, searchFn, sessionId) {
+        const id = sessionId ?? randomUUID();
+        const startedAt = new Date().toISOString();
+        const hypotheses = generateHypotheses(problem);
+        const searchResults = [];
+        let iterations = 0;
+        let stoppedEarly = false;
+        for (let i = 0; i < this.maxIterations; i++) {
+            iterations++;
+            // Select hypothesis with lowest confidence and fewest evidence
+            const active = hypotheses.filter((h) => h.status === "active");
+            if (active.length === 0)
+                break;
+            const target = active.reduce((best, h) => {
+                const score = h.confidence + h.supportingEvidence.length * 0.05;
+                const bestScore = best.confidence + best.supportingEvidence.length * 0.05;
+                return score < bestScore ? h : best;
+            });
+            // Generate search query
+            const query = hypothesisToQuery(target, problem);
+            // Search code and docs (errors are non-fatal)
+            for (const source of ["code", "docs"]) {
+                let snippets = [];
+                try {
+                    snippets = await searchFn(query, source);
+                }
+                catch {
+                    snippets = [];
+                }
+                if (snippets.length > 0) {
+                    searchResults.push({
+                        query,
+                        source,
+                        snippets: snippets.slice(0, 10),
+                        timestamp: new Date().toISOString(),
+                    });
+                }
+                // Evaluate evidence against all active hypotheses
+                for (const hyp of active) {
+                    evaluateEvidence(hyp, snippets, query);
+                }
+            }
+            // Check early stop: any hypothesis reached minConfidenceToStop?
+            const confident = hypotheses.find((h) => h.confidence >= this.minConfidenceToStop);
+            if (confident) {
+                confident.status = "confirmed";
+                stoppedEarly = true;
+                break;
+            }
+        }
+        // Finalize hypothesis statuses
+        for (const h of hypotheses) {
+            if (h.status === "active") {
+                if (h.confidence >= this.minConfidenceToStop) {
+                    h.status = "confirmed";
+                }
+                else if (h.confidence <= 0.1) {
+                    h.status = "rejected";
+                }
+                else {
+                    h.status = "inconclusive";
+                }
+            }
+        }
+        const conclusion = buildConclusion(hypotheses);
+        const recommendedStrategy = selectStrategy(conclusion);
+        const topConfidence = Math.max(...hypotheses.map((h) => h.confidence));
+        const completedAt = new Date().toISOString();
+        const session = {
+            id,
+            problem,
+            hypotheses,
+            searchResults,
+            conclusion,
+            recommendedStrategy,
+            confidence: Math.round(topConfidence * 100) / 100,
+            iterations,
+            startedAt,
+            completedAt,
+        };
+        // Persist (atomic write, non-fatal on failure)
+        this.sessions.push(session);
+        saveSessions(this.storageDir, this.sessions);
+        // Emit completion event
+        this.emit("event", {
+            kind: "agent:research_session_complete",
+            sessionId: id,
+            problem,
+            conclusion,
+            recommendedStrategy,
+            confidence: session.confidence,
+            iterations,
+            stoppedEarly,
+            timestamp: completedAt,
+        });
+        return session;
+    }
+    /**
+     * Return all research sessions loaded from storage (+ any run in this instance).
+     */
+    getSessions() {
+        return [...this.sessions];
+    }
+    /**
+     * Find the most relevant past session for a given problem using word-overlap
+     * similarity. Returns null if no session has similarity ≥ 0.3.
+     */
+    findRelevant(problem) {
+        const SIMILARITY_THRESHOLD = 0.3;
+        let best = null;
+        let bestScore = 0;
+        for (const session of this.sessions) {
+            const score = similarity(problem, session.problem);
+            if (score > bestScore) {
+                bestScore = score;
+                best = session;
+            }
+        }
+        return bestScore >= SIMILARITY_THRESHOLD ? best : null;
+    }
+}
+//# sourceMappingURL=research-loop.js.map

package/dist/research-loop.js.map

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

package/dist/resolve-memory-path.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @module resolve-memory-path
+ * @description Cross-platform, security-isolated memory path resolver.
+ *
+ * - Per-user isolation: uses os.userInfo().username for user-scoped subdirectories.
+ * - Platform detection: Windows (%APPDATA%), macOS (~/Library/Application Support), Linux (~/.yuan).
+ * - Cloud infrastructure detection: GCP, Azure, Oracle, Cloud Run.
+ * - Project-scoped path: <projectPath>/.yuan/ for project-level files.
+ * - Unix directory permissions: 0o700 (owner-only) for user-level dirs.
+ */
+export interface MemoryPaths {
+    userBase: string;
+    isCloud: boolean;
+    platform: "windows" | "macos" | "linux" | "cloud";
+}
+/**
+ * Returns the user-level base memory directory and creates it with 0o700 permissions.
+ * Path is user-scoped to prevent cross-user data leakage.
+ */
+export declare function resolveUserMemoryBase(): MemoryPaths;
+/**
+ * Returns the project-scoped memory base directory path.
+ * Does NOT create the directory — caller is responsible.
+ */
+export declare function resolveProjectMemoryBase(projectPath: string): string;
+/**
+ * Resolves a memory file path.
+ * If projectPath is given, returns the project-scoped path.
+ * Otherwise returns the user-level path (and ensures the user base dir exists).
+ */
+export declare function resolveMemoryFile(filename: string, projectPath?: string): string;
+//# sourceMappingURL=resolve-memory-path.d.ts.map

package/dist/resolve-memory-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-memory-path.d.ts","sourceRoot":"","sources":["../src/resolve-memory-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;CACnD;AAuBD;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,WAAW,CAwCnD;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAMhF"}

package/dist/resolve-memory-path.js

@@ -0,0 +1,97 @@
+/**
+ * @module resolve-memory-path
+ * @description Cross-platform, security-isolated memory path resolver.
+ *
+ * - Per-user isolation: uses os.userInfo().username for user-scoped subdirectories.
+ * - Platform detection: Windows (%APPDATA%), macOS (~/Library/Application Support), Linux (~/.yuan).
+ * - Cloud infrastructure detection: GCP, Azure, Oracle, Cloud Run.
+ * - Project-scoped path: <projectPath>/.yuan/ for project-level files.
+ * - Unix directory permissions: 0o700 (owner-only) for user-level dirs.
+ */
+import { homedir, userInfo, platform } from "node:os";
+import { join } from "node:path";
+import { mkdirSync, accessSync, constants } from "node:fs";
+/** Detect cloud infrastructure via environment variables. */
+function detectCloud() {
+    return !!(process.env["CLOUD_SHELL"] ||
+        process.env["GOOGLE_CLOUD_PROJECT"] ||
+        process.env["AZURE_SUBSCRIPTION_ID"] ||
+        process.env["OCI_RESOURCE_PRINCIPAL_VERSION"] ||
+        process.env["K_SERVICE"]);
+}
+/** Check if a directory is writable. */
+function isWritable(dirPath) {
+    try {
+        accessSync(dirPath, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns the user-level base memory directory and creates it with 0o700 permissions.
+ * Path is user-scoped to prevent cross-user data leakage.
+ */
+export function resolveUserMemoryBase() {
+    const username = userInfo().username;
+    const isCloud = detectCloud();
+    const osPlatform = platform();
+    let userBase;
+    let resolvedPlatform;
+    if (osPlatform === "win32") {
+        // Windows: %APPDATA%\yuan\<username>\ or fallback %USERPROFILE%\.yuan\<username>\
+        const appData = process.env["APPDATA"];
+        if (appData) {
+            userBase = join(appData, "yuan", username);
+        }
+        else {
+            userBase = join(homedir(), ".yuan", username);
+        }
+        resolvedPlatform = "windows";
+    }
+    else if (osPlatform === "darwin") {
+        // macOS: ~/Library/Application Support/yuan/<username>/ if writable, else ~/.yuan/<username>/
+        const libAppSupport = join(homedir(), "Library", "Application Support");
+        if (isWritable(libAppSupport)) {
+            userBase = join(libAppSupport, "yuan", username);
+        }
+        else {
+            userBase = join(homedir(), ".yuan", username);
+        }
+        resolvedPlatform = isCloud ? "cloud" : "macos";
+    }
+    else {
+        // Linux / Cloud / Other: ~/.yuan/<username>/
+        userBase = join(homedir(), ".yuan", username);
+        resolvedPlatform = isCloud ? "cloud" : "linux";
+    }
+    // Create directory with owner-only permissions on Unix
+    if (osPlatform !== "win32") {
+        mkdirSync(userBase, { recursive: true, mode: 0o700 });
+    }
+    else {
+        mkdirSync(userBase, { recursive: true });
+    }
+    return { userBase, isCloud, platform: resolvedPlatform };
+}
+/**
+ * Returns the project-scoped memory base directory path.
+ * Does NOT create the directory — caller is responsible.
+ */
+export function resolveProjectMemoryBase(projectPath) {
+    return join(projectPath, ".yuan");
+}
+/**
+ * Resolves a memory file path.
+ * If projectPath is given, returns the project-scoped path.
+ * Otherwise returns the user-level path (and ensures the user base dir exists).
+ */
+export function resolveMemoryFile(filename, projectPath) {
+    if (projectPath) {
+        return join(resolveProjectMemoryBase(projectPath), filename);
+    }
+    const { userBase } = resolveUserMemoryBase();
+    return join(userBase, filename);
+}
+//# sourceMappingURL=resolve-memory-path.js.map

package/dist/resolve-memory-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-memory-path.js","sourceRoot":"","sources":["../src/resolve-memory-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAQ3D,6DAA6D;AAC7D,SAAS,WAAW;IAClB,OAAO,CAAC,CAAC,CACP,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;QAC1B,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;QACnC,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC;QACpC,OAAO,CAAC,GAAG,CAAC,gCAAgC,CAAC;QAC7C,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CACzB,CAAC;AACJ,CAAC;AAED,wCAAwC;AACxC,SAAS,UAAU,CAAC,OAAe;IACjC,IAAI,CAAC;QACH,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,QAAQ,GAAG,QAAQ,EAAE,CAAC,QAAQ,CAAC;IACrC,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC;IAC9B,MAAM,UAAU,GAAG,QAAQ,EAAE,CAAC;IAE9B,IAAI,QAAgB,CAAC;IACrB,IAAI,gBAAyC,CAAC;IAE9C,IAAI,UAAU,KAAK,OAAO,EAAE,CAAC;QAC3B,kFAAkF;QAClF,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACvC,IAAI,OAAO,EAAE,CAAC;YACZ,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC7C,CAAC;aAAM,CAAC;YACN,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QAChD,CAAC;QACD,gBAAgB,GAAG,SAAS,CAAC;IAC/B,CAAC;SAAM,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;QACnC,8FAA8F;QAC9F,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,qBAAqB,CAAC,CAAC;QACxE,IAAI,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;YAC9B,QAAQ,GAAG,IAAI,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;QACnD,CAAC;aAAM,CAAC;YACN,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QAChD,CAAC;QACD,gBAAgB,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IACjD,CAAC;SAAM,CAAC;QACN,6CAA6C;QAC7C,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC9C,gBAAgB,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IACjD,CAAC;IAED,uDAAuD;IACvD,IAAI,UAAU,KAAK,OAAO,EAAE,CAAC;QAC3B,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACxD,CAAC;SAAM,CAAC;QACN,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,WAAmB;IAC1D,OAAO,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,WAAoB;IACtE,IAAI,WAAW,EAAE,CAAC;QAChB,OAAO,IAAI,CAAC,wBAAwB,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC/D,CAAC;IACD,MAAM,EAAE,QAAQ,EAAE,GAAG,qBAAqB,EAAE,CAAC;IAC7C,OAAO,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAClC,CAAC"}

package/dist/safe-bounds.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @module safe-bounds
+ * @description Centralized resource bounds to prevent unbounded memory growth,
+ * context explosions, and runaway string allocations across the agent system.
+ *
+ * Every array that grows over time and every string from an external source
+ * must be capped here. This is the single source of truth for all size limits.
+ *
+ * Rule: External data enters → truncate(). Arrays accumulate → cap().
+ */
+export declare const BOUNDS: {
+    /** Max tracked changed files per agent run */
+    readonly changedFiles: 200;
+    /** Max tool results kept in memory (allToolResults) */
+    readonly allToolResults: 30;
+    /** Max tool results since last replan */
+    readonly toolResultsSinceReplan: 20;
+    /** Max messages in context (pruned by message-pruner) */
+    readonly messages: 40;
+    /** Max reflexion FIFO entries */
+    readonly reflexionEntries: 100;
+    /** Max vector store chunks in memory */
+    readonly vectorChunks: 500;
+    /** Max reasoning tree depth */
+    readonly reasoningDepth: 20;
+    /** Max reasoning tree total nodes */
+    readonly reasoningNodes: 200;
+    /** Max session chain length (continuation parent→child) */
+    readonly sessionChains: 50;
+    /** Max background task steps in TUI */
+    readonly bgTaskSteps: 20;
+    /** Max background tasks tracked simultaneously */
+    readonly bgTasks: 10;
+    /** Max deferred fix prompts per iteration */
+    readonly deferredFixes: 5;
+    /** Max skill-learner pattern entries */
+    readonly skillPatterns: 500;
+    /** Max MCP servers that can be registered */
+    readonly mcpServers: 20;
+    /** Shell command stdout (chars) — already enforced in shell-exec.ts */
+    readonly shellStdout: 100000;
+    /** Shell command stderr (chars) — already enforced in shell-exec.ts */
+    readonly shellStderr: 50000;
+    /** File read content (chars) — already enforced in file-read.ts */
+    readonly fileContent: 50000;
+    /** Git diff output (chars) */
+    readonly gitDiff: 15000;
+    /** Web scrape / fetch result (chars) */
+    readonly webContent: 30000;
+    /** TSC error output injected into LLM context (chars) */
+    readonly tscOutput: 3000;
+    /** Single reflexion entry body (chars) */
+    readonly reflexionEntryBody: 2000;
+    /** Tool result content stored in session persistence (chars) — 4KB */
+    readonly toolResultPersistence: 4096;
+    /** LLM thinking/reasoning content per message (chars) */
+    readonly thinkingContent: 8000;
+    /** Single QA issue message (chars) */
+    readonly qaIssueMessage: 200;
+    /** Architecture summary cache (chars) */
+    readonly archSummary: 20000;
+    /** Error signature for repeat detection (chars) */
+    readonly errorSignature: 500;
+    /** Single agent event content (chars) */
+    readonly agentEventContent: 2000;
+};
+/**
+ * Cap an array to the last `max` elements.
+ * Keeps the most recent entries (LIFO window).
+ */
+export declare function cap<T>(arr: T[], max: number): T[];
+/**
+ * Cap an array to the first `max` elements.
+ * Useful for ID lists, file lists, etc. where order matters.
+ */
+export declare function capHead<T>(arr: T[], max: number): T[];
+/**
+ * Truncate a string to `max` characters.
+ * Appends a labeled suffix showing how many chars were removed.
+ */
+export declare function truncate(s: string, max: number, label?: string): string;
+/**
+ * Truncate from the start of a string (keep the end — useful for logs/output
+ * where the most relevant info is at the bottom).
+ */
+export declare function truncateHead(s: string, max: number, label?: string): string;
+/**
+ * Push an item into an array and cap it in-place.
+ * Returns the (possibly truncated) array.
+ */
+export declare function pushCapped<T>(arr: T[], item: T, max: number): T[];
+/**
+ * Safe JSON stringify that never throws and caps output size.
+ * Used for persisting data to disk without pretty-printing (no OOM).
+ */
+export declare function safeJsonStringify(value: unknown, maxChars?: number): string;
+/**
+ * Safe JSON parse that never throws.
+ */
+export declare function safeJsonParse<T = unknown>(s: string, fallback: T): T;
+//# sourceMappingURL=safe-bounds.d.ts.map

package/dist/safe-bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-bounds.d.ts","sourceRoot":"","sources":["../src/safe-bounds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,eAAO,MAAM,MAAM;IAEjB,8CAA8C;;IAE9C,uDAAuD;;IAEvD,yCAAyC;;IAEzC,yDAAyD;;IAEzD,iCAAiC;;IAEjC,wCAAwC;;IAExC,+BAA+B;;IAE/B,qCAAqC;;IAErC,2DAA2D;;IAE3D,uCAAuC;;IAEvC,kDAAkD;;IAElD,6CAA6C;;IAE7C,wCAAwC;;IAExC,6CAA6C;;IAI7C,uEAAuE;;IAEvE,uEAAuE;;IAEvE,mEAAmE;;IAEnE,8BAA8B;;IAE9B,wCAAwC;;IAExC,yDAAyD;;IAEzD,0CAA0C;;IAE1C,sEAAsE;;IAEtE,yDAAyD;;IAEzD,sCAAsC;;IAEtC,yCAAyC;;IAEzC,mDAAmD;;IAEnD,yCAAyC;;CAEjC,CAAC;AAIX;;;GAGG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,EAAE,CAEjD;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,EAAE,CAErD;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,SAAY,GAAG,MAAM,CAI1E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,SAAY,GAAG,MAAM,CAI9E;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,EAAE,CAMjE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAa,GAAG,MAAM,CAO/E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAMpE"}