@yuaone/core 0.9.8 → 0.9.10

package/dist/autonomous/patch-tournament.js

@@ -0,0 +1,150 @@
+/**
+ * @module autonomous/patch-tournament
+ * @description Patch Tournament Executor — generates N candidate patches for a goal,
+ * scores each with the QA pipeline, and selects the best.
+ *
+ * Design:
+ * - Takes a "run agent" callback (injected from CLI — keeps this module pure)
+ * - Runs candidates sequentially (not parallel) to avoid file conflicts
+ * - Scores via QAPipeline + diff stats from evidence history
+ * - Emits agent:tournament_result with winner index
+ *
+ * Constraints:
+ * - Does NOT touch the main agent loop (deterministic)
+ * - All scoring goes through QAPipeline (no bypass)
+ * - Goes through OverheadGovernor (caller must check shouldRunTournament())
+ * - Emits events at every candidate + final result
+ */
+import { EventEmitter } from "node:events";
+import { randomUUID } from "node:crypto";
+import { QAPipeline } from "../qa-pipeline.js";
+// ─── Scoring ─────────────────────────────────────────────────────────────────
+function scoreQAResult(qa) {
+    if (!qa)
+        return 0;
+    const base = qa.overall === "pass" ? 1.0 : qa.overall === "warn" ? 0.6 : 0.2;
+    const passRatio = qa.totalChecks > 0 ? qa.passed / qa.totalChecks : 0;
+    const failPenalty = qa.failures * 0.1;
+    return Math.max(0, Math.min(1, base * passRatio - failPenalty));
+}
+// ─── PatchTournamentExecutor ─────────────────────────────────────────────────
+export class PatchTournamentExecutor extends EventEmitter {
+    config;
+    constructor(config = {}) {
+        super();
+        const n = config.candidates ?? 3;
+        this.config = {
+            candidates: n,
+            strategies: config.strategies ?? this.defaultStrategies(n),
+            qaConfig: config.qaConfig ?? {},
+            projectPath: config.projectPath ?? process.cwd(),
+        };
+    }
+    /**
+     * Run the tournament. For each candidate:
+     * 1. Call runAgent() to generate a patch
+     * 2. Score with QAPipeline
+     * 3. Track best
+     *
+     * Returns TournamentResult with winner index.
+     * Emits agent:tournament_result at completion.
+     *
+     * NOTE: The CLI is responsible for:
+     * - Stashing current git state before the first candidate
+     * - Restoring baseline between candidates (git stash pop + git stash)
+     * - Applying the winner's patch after selection
+     */
+    async run(goal, runAgent, taskId) {
+        const resolvedTaskId = taskId ?? randomUUID();
+        const timestamp = Date.now();
+        const candidates = [];
+        for (let i = 0; i < this.config.candidates; i++) {
+            const strategy = this.config.strategies[i] ?? `strategy-${i}`;
+            this.emitProgress(resolvedTaskId, i, "running", strategy);
+            let filesChanged = [];
+            let qaResult = null;
+            try {
+                filesChanged = await runAgent(goal, strategy, i);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                this.emitProgress(resolvedTaskId, i, "failed", `${strategy}: ${msg}`);
+            }
+            // Score with QA pipeline if files were changed
+            if (filesChanged.length > 0) {
+                try {
+                    const qa = new QAPipeline({
+                        projectPath: this.config.projectPath,
+                        level: "quick",
+                        ...this.config.qaConfig,
+                    });
+                    qaResult = await qa.run(filesChanged);
+                }
+                catch { /* QA failure is non-fatal */ }
+            }
+            const score = scoreQAResult(qaResult);
+            const reason = this.describeScore(qaResult, score, filesChanged.length);
+            candidates.push({ index: i, strategy, filesChanged, qaResult, score, reason });
+            this.emitProgress(resolvedTaskId, i, "scored", reason);
+        }
+        // Select winner (highest score; tie-break by fewer files changed)
+        let winner = 0;
+        for (let i = 1; i < candidates.length; i++) {
+            const curr = candidates[i];
+            const best = candidates[winner];
+            if (curr.score > best.score ||
+                (curr.score === best.score && curr.filesChanged.length < best.filesChanged.length)) {
+                winner = i;
+            }
+        }
+        const result = {
+            taskId: resolvedTaskId,
+            goal,
+            winner,
+            candidates,
+            qualityScore: candidates[winner]?.score ?? 0,
+            timestamp,
+        };
+        this.emitResult(result);
+        return result;
+    }
+    // ─── private ───────────────────────────────────────────────────────────────
+    defaultStrategies(n) {
+        const base = [
+            "direct-fix",
+            "minimal-change",
+            "refactor-first",
+            "test-driven",
+            "defensive",
+        ];
+        return base.slice(0, n);
+    }
+    describeScore(qa, score, fileCount) {
+        if (!qa)
+            return `no QA result (${fileCount} files)`;
+        return `${qa.overall}: ${qa.passed}/${qa.totalChecks} checks, score=${score.toFixed(2)} (${fileCount} files)`;
+    }
+    emitProgress(taskId, candidateIdx, state, detail) {
+        const event = {
+            kind: "agent:bg_update",
+            agentId: `tournament-${taskId}`,
+            agentLabel: `Tournament[${candidateIdx}]`,
+            eventType: state === "failed" ? "warning" : "info",
+            message: `candidate ${candidateIdx} ${state}: ${detail}`,
+            timestamp: Date.now(),
+        };
+        this.emit("event", event);
+    }
+    emitResult(result) {
+        const event = {
+            kind: "agent:tournament_result",
+            taskId: result.taskId,
+            winner: result.winner,
+            candidates: result.candidates.length,
+            qualityScore: result.qualityScore,
+            timestamp: result.timestamp,
+        };
+        this.emit("event", event);
+    }
+}
+//# sourceMappingURL=patch-tournament.js.map

package/dist/autonomous/patch-tournament.js.map

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

package/dist/autonomous/research-agent.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @module autonomous/research-agent
+ * @description Research Agent — combines MCP web search + repo search + docs fetch,
+ * ranks sources, and emits a structured research_result event.
+ *
+ * Design:
+ * - Does NOT call the LLM directly (keeps the main loop deterministic)
+ * - Orchestrates: MCP search tools + local repo grep/glob via ToolExecutor
+ * - Scoring: naive TF-IDF relevance ranking over snippets
+ * - Output: agent:research_result event + ResearchResult object
+ *
+ * Constraints:
+ * - All outputs emit events (observable)
+ * - Integrates with TraceRecorder via event emission
+ * - Goes through OverheadGovernor (caller must check shouldRunResearch())
+ */
+import { EventEmitter } from "node:events";
+import type { ToolExecutor } from "../types.js";
+export interface ResearchSource {
+    title: string;
+    url: string;
+    snippet: string;
+    /** "web" | "repo" | "docs" | "mcp:<server-name>" */
+    source: string;
+    /** 0.0–1.0 relevance score */
+    relevance: number;
+}
+export interface ResearchResult {
+    taskId: string;
+    query: string;
+    summary: string;
+    sources: ResearchSource[];
+    /** 0.0–1.0 confidence based on source count + relevance distribution */
+    confidence: number;
+    timestamp: number;
+}
+export interface ResearchAgentConfig {
+    /** Max number of MCP search results to collect */
+    maxMcpResults?: number;
+    /** Max number of repo grep results to collect */
+    maxRepoResults?: number;
+    /** Project root for local repo search */
+    projectPath?: string;
+    /** MCP tool names that perform web search (prefix match) */
+    mcpSearchTools?: string[];
+}
+export declare class ResearchAgent extends EventEmitter {
+    private readonly toolExecutor;
+    private readonly config;
+    constructor(toolExecutor: ToolExecutor, config?: ResearchAgentConfig);
+    /**
+     * Run research for a query. Returns structured ResearchResult.
+     * Emits agent:research_result when complete.
+     */
+    research(query: string, taskId?: string): Promise<ResearchResult>;
+    private searchRepo;
+    private searchMcp;
+    private parseMcpSearchOutput;
+    private rankSources;
+    /** Naive TF-IDF-like scoring: count query term hits / total terms */
+    private scoreRelevance;
+    private buildSummary;
+    private computeConfidence;
+    private emitResult;
+}
+//# sourceMappingURL=research-agent.d.ts.map

package/dist/autonomous/research-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-agent.d.ts","sourceRoot":"","sources":["../../src/autonomous/research-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,aAAa,CAAC;AAK5D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,kDAAkD;IAClD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAID,qBAAa,aAAc,SAAQ,YAAY;IAI3C,OAAO,CAAC,QAAQ,CAAC,YAAY;IAH/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;gBAGpC,YAAY,EAAE,YAAY,EAC3C,MAAM,GAAE,mBAAwB;IAelC;;;OAGG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;YAsCzD,UAAU;YA2CV,SAAS;IAqBvB,OAAO,CAAC,oBAAoB;IA0B5B,OAAO,CAAC,WAAW;IAanB,qEAAqE;IACrE,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,UAAU;CAWnB"}

package/dist/autonomous/research-agent.js

@@ -0,0 +1,210 @@
+/**
+ * @module autonomous/research-agent
+ * @description Research Agent — combines MCP web search + repo search + docs fetch,
+ * ranks sources, and emits a structured research_result event.
+ *
+ * Design:
+ * - Does NOT call the LLM directly (keeps the main loop deterministic)
+ * - Orchestrates: MCP search tools + local repo grep/glob via ToolExecutor
+ * - Scoring: naive TF-IDF relevance ranking over snippets
+ * - Output: agent:research_result event + ResearchResult object
+ *
+ * Constraints:
+ * - All outputs emit events (observable)
+ * - Integrates with TraceRecorder via event emission
+ * - Goes through OverheadGovernor (caller must check shouldRunResearch())
+ */
+import { EventEmitter } from "node:events";
+import { randomUUID } from "node:crypto";
+import { BOUNDS, truncate } from "../safe-bounds.js";
+// ─── ResearchAgent ────────────────────────────────────────────────────────────
+export class ResearchAgent extends EventEmitter {
+    toolExecutor;
+    config;
+    constructor(toolExecutor, config = {}) {
+        super();
+        this.toolExecutor = toolExecutor;
+        this.config = {
+            maxMcpResults: config.maxMcpResults ?? 10,
+            maxRepoResults: config.maxRepoResults ?? 20,
+            projectPath: config.projectPath ?? process.cwd(),
+            mcpSearchTools: config.mcpSearchTools ?? [
+                "brave_search", "spider_search", "fetch_fetch",
+                "github_search_code", "github_search_repositories",
+                "search", "web_search",
+            ],
+        };
+    }
+    /**
+     * Run research for a query. Returns structured ResearchResult.
+     * Emits agent:research_result when complete.
+     */
+    async research(query, taskId) {
+        const resolvedTaskId = taskId ?? randomUUID();
+        const timestamp = Date.now();
+        const sources = [];
+        // 1. Repo search — grep for query terms in project
+        const repoResults = await this.searchRepo(query);
+        sources.push(...repoResults);
+        // 2. MCP web/docs search (best-effort — fails gracefully)
+        const mcpResults = await this.searchMcp(query);
+        sources.push(...mcpResults);
+        // 3. Rank by relevance
+        const ranked = this.rankSources(query, sources)
+            .slice(0, this.config.maxMcpResults + this.config.maxRepoResults);
+        // 4. Build summary from top sources
+        const summary = this.buildSummary(query, ranked);
+        // 5. Compute confidence
+        const confidence = this.computeConfidence(ranked);
+        const result = {
+            taskId: resolvedTaskId,
+            query,
+            summary,
+            sources: ranked,
+            confidence,
+            timestamp,
+        };
+        this.emitResult(result);
+        return result;
+    }
+    // ─── private ───────────────────────────────────────────────────────────────
+    async searchRepo(query) {
+        const results = [];
+        // Extract meaningful terms (strip common words)
+        const terms = query.split(/\s+/)
+            .filter(t => t.length > 3 && !/^(the|and|for|with|that|this|from|into|when|where)$/i.test(t))
+            .slice(0, 4);
+        if (terms.length === 0)
+            return results;
+        const pattern = terms.join("|");
+        try {
+            const grepResult = await this.toolExecutor.execute({
+                id: `research-grep-${Date.now()}`,
+                name: "grep",
+                arguments: JSON.stringify({
+                    pattern,
+                    path: this.config.projectPath,
+                    recursive: true,
+                    maxResults: this.config.maxRepoResults,
+                    include: "*.ts,*.tsx,*.js,*.jsx,*.md",
+                }),
+            });
+            if (grepResult.success && grepResult.output) {
+                const lines = grepResult.output.split("\n").filter(Boolean).slice(0, this.config.maxRepoResults);
+                for (const line of lines) {
+                    const colonIdx = line.indexOf(":");
+                    if (colonIdx === -1)
+                        continue;
+                    const filePath = line.slice(0, colonIdx);
+                    const snippet = truncate(line.slice(colonIdx + 1).trim(), 200);
+                    results.push({
+                        title: filePath,
+                        url: `file://${filePath}`,
+                        snippet,
+                        source: "repo",
+                        relevance: 0, // will be scored later
+                    });
+                }
+            }
+        }
+        catch { /* non-fatal */ }
+        return results;
+    }
+    async searchMcp(query) {
+        const results = [];
+        // Try each MCP search tool — stop at first successful one
+        for (const toolName of this.config.mcpSearchTools) {
+            try {
+                const mcpResult = await this.toolExecutor.execute({
+                    id: `research-mcp-${toolName}-${Date.now()}`,
+                    name: toolName,
+                    arguments: JSON.stringify({ query, q: query, search: query }),
+                });
+                if (!mcpResult.success || !mcpResult.output)
+                    continue;
+                // Parse result — may be JSON array or plain text
+                const parsed = this.parseMcpSearchOutput(mcpResult.output, toolName);
+                results.push(...parsed.slice(0, this.config.maxMcpResults));
+                if (results.length > 0)
+                    break; // first working tool is enough
+            }
+            catch { /* non-fatal — tool may not be loaded */ }
+        }
+        return results;
+    }
+    parseMcpSearchOutput(output, toolName) {
+        // Try JSON array first (structured MCP output)
+        try {
+            const parsed = JSON.parse(output);
+            if (Array.isArray(parsed)) {
+                return parsed.slice(0, 10).map((item) => ({
+                    title: String(item["title"] ?? item["name"] ?? ""),
+                    url: String(item["url"] ?? item["link"] ?? ""),
+                    snippet: truncate(String(item["snippet"] ?? item["description"] ?? item["body"] ?? ""), 300),
+                    source: `mcp:${toolName}`,
+                    relevance: 0,
+                }));
+            }
+        }
+        catch { /* not JSON */ }
+        // Fallback: plain text, each non-empty line is a snippet
+        const lines = output.split("\n").filter(l => l.trim().length > 20).slice(0, 5);
+        return lines.map((line, i) => ({
+            title: `Result ${i + 1}`,
+            url: "",
+            snippet: truncate(line, 300),
+            source: `mcp:${toolName}`,
+            relevance: 0,
+        }));
+    }
+    rankSources(query, sources) {
+        const queryTerms = query.toLowerCase().split(/\s+/).filter(t => t.length > 2);
+        return sources
+            .map(s => ({
+            ...s,
+            relevance: this.scoreRelevance(`${s.title} ${s.snippet}`.toLowerCase(), queryTerms),
+        }))
+            .sort((a, b) => b.relevance - a.relevance);
+    }
+    /** Naive TF-IDF-like scoring: count query term hits / total terms */
+    scoreRelevance(text, queryTerms) {
+        if (queryTerms.length === 0)
+            return 0.5;
+        const hits = queryTerms.filter(t => text.includes(t)).length;
+        return hits / queryTerms.length;
+    }
+    buildSummary(query, sources) {
+        if (sources.length === 0) {
+            return `No sources found for: "${query}"`;
+        }
+        const repoCount = sources.filter(s => s.source === "repo").length;
+        const webCount = sources.filter(s => s.source.startsWith("mcp:")).length;
+        const top3 = sources.slice(0, 3)
+            .map(s => `- ${s.title}: ${s.snippet.slice(0, 100)}`)
+            .join("\n");
+        return [
+            `Research for: "${query}"`,
+            `Found ${sources.length} sources (${repoCount} repo, ${webCount} web).`,
+            `Top results:\n${top3}`,
+        ].join("\n");
+    }
+    computeConfidence(sources) {
+        if (sources.length === 0)
+            return 0;
+        const avgRelevance = sources.reduce((s, r) => s + r.relevance, 0) / sources.length;
+        const coverageFactor = Math.min(sources.length / 5, 1.0); // 5 sources = max coverage
+        return Math.round(avgRelevance * coverageFactor * 100) / 100;
+    }
+    emitResult(result) {
+        const event = {
+            kind: "agent:research_result",
+            taskId: result.taskId,
+            summary: truncate(result.summary, BOUNDS.toolResultPersistence),
+            sources: result.sources.slice(0, 20), // cap at 20 sources in event payload
+            confidence: result.confidence,
+            timestamp: result.timestamp,
+        };
+        this.emit("event", event);
+    }
+}
+//# sourceMappingURL=research-agent.js.map

package/dist/autonomous/research-agent.js.map

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

package/dist/autonomous/task-memory.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @module autonomous/task-memory
+ * @description Long Horizon Task Memory — persists task-level state under .yuan/tasks/.
+ *
+ * Stores the full lifecycle of an engineering task: goal, phase, files touched,
+ * evidence history, and final status. Designed for multi-session tasks that
+ * span multiple agent runs (e.g. a multi-day refactor).
+ *
+ * Storage: .yuan/tasks/<taskId>.json (one file per task)
+ * All writes are atomic (write to .tmp then rename).
+ */
+import { EventEmitter } from "node:events";
+export type TaskStatus = "running" | "completed" | "failed" | "paused";
+export type TaskPhase = "research" | "planning" | "implement" | "verify" | "finalize";
+export interface EvidenceEntry {
+    /** Unix ms */
+    timestamp: number;
+    filePath: string;
+    diffStats: {
+        added: number;
+        removed: number;
+    } | null;
+    syntax: "ok" | "error" | "skipped";
+    source: "evidence_report" | "qa_result" | "manual";
+}
+export interface TaskState {
+    taskId: string;
+    goal: string;
+    currentPhase: TaskPhase;
+    filesTouched: string[];
+    evidenceHistory: EvidenceEntry[];
+    status: TaskStatus;
+    /** ISO timestamp when task was created */
+    createdAt: string;
+    /** ISO timestamp of last update */
+    updatedAt: string;
+    /** Optional: path to the plan file */
+    planPath?: string;
+    /** Optional: final summary on completion */
+    summary?: string;
+}
+export declare class TaskMemory extends EventEmitter {
+    private readonly tasksDir;
+    constructor(tasksDir?: string);
+    /** Create or overwrite a task. Emits agent:task_memory_update. */
+    create(taskId: string, goal: string): TaskState;
+    /** Load task state. Returns null if not found. */
+    load(taskId: string): TaskState | null;
+    /** Transition to a new phase. */
+    setPhase(taskId: string, phase: TaskPhase): TaskState | null;
+    /** Mark task complete or failed. */
+    finish(taskId: string, status: "completed" | "failed", summary?: string): TaskState | null;
+    /** Append an evidence entry to the task history. */
+    appendEvidence(taskId: string, entry: EvidenceEntry): TaskState | null;
+    /** List all tasks, sorted by updatedAt descending. */
+    list(): TaskState[];
+    /** Remove a task file. */
+    delete(taskId: string): boolean;
+    private taskPath;
+    private save;
+    private emitUpdate;
+}
+//# sourceMappingURL=task-memory.d.ts.map

package/dist/autonomous/task-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-memory.d.ts","sourceRoot":"","sources":["../../src/autonomous/task-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAK3C,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AACvE,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEtF,MAAM,WAAW,aAAa;IAC5B,cAAc;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACrD,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;IACnC,MAAM,EAAE,iBAAiB,GAAG,WAAW,GAAG,QAAQ,CAAC;CACpD;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,SAAS,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,eAAe,EAAE,aAAa,EAAE,CAAC;IACjC,MAAM,EAAE,UAAU,CAAC;IACnB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,qBAAa,UAAW,SAAQ,YAAY;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,CAAC,EAAE,MAAM;IAM7B,kEAAkE;IAClE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS;IAgB/C,kDAAkD;IAClD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAStC,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI;IAU5D,oCAAoC;IACpC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,QAAQ,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAW1F,oDAAoD;IACpD,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI;IAgBtE,sDAAsD;IACtD,IAAI,IAAI,SAAS,EAAE;IAgBnB,0BAA0B;IAC1B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAW/B,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,IAAI;IAOZ,OAAO,CAAC,UAAU;CAUnB"}

package/dist/autonomous/task-memory.js

@@ -0,0 +1,143 @@
+/**
+ * @module autonomous/task-memory
+ * @description Long Horizon Task Memory — persists task-level state under .yuan/tasks/.
+ *
+ * Stores the full lifecycle of an engineering task: goal, phase, files touched,
+ * evidence history, and final status. Designed for multi-session tasks that
+ * span multiple agent runs (e.g. a multi-day refactor).
+ *
+ * Storage: .yuan/tasks/<taskId>.json (one file per task)
+ * All writes are atomic (write to .tmp then rename).
+ */
+import { mkdirSync, writeFileSync, readFileSync, renameSync, readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { EventEmitter } from "node:events";
+// ─── TaskMemory ──────────────────────────────────────────────────────────────
+export class TaskMemory extends EventEmitter {
+    tasksDir;
+    constructor(tasksDir) {
+        super();
+        this.tasksDir = tasksDir ?? join(homedir(), ".yuan", "tasks");
+        mkdirSync(this.tasksDir, { recursive: true });
+    }
+    /** Create or overwrite a task. Emits agent:task_memory_update. */
+    create(taskId, goal) {
+        const state = {
+            taskId,
+            goal,
+            currentPhase: "research",
+            filesTouched: [],
+            evidenceHistory: [],
+            status: "running",
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+        };
+        this.save(state);
+        this.emitUpdate(state);
+        return state;
+    }
+    /** Load task state. Returns null if not found. */
+    load(taskId) {
+        try {
+            const raw = readFileSync(this.taskPath(taskId), "utf-8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Transition to a new phase. */
+    setPhase(taskId, phase) {
+        const state = this.load(taskId);
+        if (!state)
+            return null;
+        state.currentPhase = phase;
+        state.updatedAt = new Date().toISOString();
+        this.save(state);
+        this.emitUpdate(state);
+        return state;
+    }
+    /** Mark task complete or failed. */
+    finish(taskId, status, summary) {
+        const state = this.load(taskId);
+        if (!state)
+            return null;
+        state.status = status;
+        state.summary = summary;
+        state.updatedAt = new Date().toISOString();
+        this.save(state);
+        this.emitUpdate(state);
+        return state;
+    }
+    /** Append an evidence entry to the task history. */
+    appendEvidence(taskId, entry) {
+        const state = this.load(taskId);
+        if (!state)
+            return null;
+        state.evidenceHistory.push(entry);
+        // Cap history at 500 entries to prevent unbounded growth
+        if (state.evidenceHistory.length > 500) {
+            state.evidenceHistory = state.evidenceHistory.slice(-500);
+        }
+        if (!state.filesTouched.includes(entry.filePath)) {
+            state.filesTouched.push(entry.filePath);
+        }
+        state.updatedAt = new Date().toISOString();
+        this.save(state);
+        return state;
+    }
+    /** List all tasks, sorted by updatedAt descending. */
+    list() {
+        try {
+            return readdirSync(this.tasksDir)
+                .filter(f => f.endsWith(".json"))
+                .map(f => {
+                try {
+                    return JSON.parse(readFileSync(join(this.tasksDir, f), "utf-8"));
+                }
+                catch {
+                    return null;
+                }
+            })
+                .filter((s) => s !== null)
+                .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Remove a task file. */
+    delete(taskId) {
+        try {
+            unlinkSync(this.taskPath(taskId));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ─── private ───────────────────────────────────────────────────────────────
+    taskPath(taskId) {
+        // Sanitize taskId to prevent path traversal
+        const safe = taskId.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 80);
+        return join(this.tasksDir, `${safe}.json`);
+    }
+    save(state) {
+        const path = this.taskPath(state.taskId);
+        const tmp = path + ".tmp";
+        writeFileSync(tmp, JSON.stringify(state, null, 2), "utf-8");
+        renameSync(tmp, path);
+    }
+    emitUpdate(state) {
+        const event = {
+            kind: "agent:task_memory_update",
+            taskId: state.taskId,
+            phase: state.currentPhase,
+            status: state.status,
+            timestamp: Date.now(),
+        };
+        this.emit("event", event);
+    }
+}
+//# sourceMappingURL=task-memory.js.map