@yuaone/core 0.9.7 → 0.9.9

package/dist/project-executive.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @module project-executive
+ * @description Long-Horizon Project Executive — manages project-level goals, milestones,
+ * stalled task detection, and resume points.
+ *
+ * Storage: ~/.yuan/projects/{projectId}/executive.json
+ * projectId = stable 8-char hash of projectPath
+ *
+ * Design:
+ * - Event-driven observer ONLY — does NOT mutate agent-loop state
+ * - Reads from TaskMemory but does not write to it
+ * - All persistence is atomic (.tmp + renameSync)
+ * - Emits structured events for all state transitions
+ */
+import { EventEmitter } from "node:events";
+export type GoalStatus = "active" | "completed" | "abandoned";
+export type GoalStrategy = "bugfix" | "refactor" | "migration" | "feature" | "investigation";
+export interface ProjectGoal {
+    id: string;
+    description: string;
+    strategy: GoalStrategy;
+    status: GoalStatus;
+    childTaskIds: string[];
+    estimatedIterations: number;
+    createdAt: string;
+    completedAt?: string;
+}
+export interface ProjectMilestone {
+    id: string;
+    description: string;
+    goalId: string;
+    targetIteration: number;
+    status: "pending" | "reached" | "missed";
+    reachedAt?: string;
+}
+export interface StalledTask {
+    taskId: string;
+    stallReason: "iteration_overrun" | "repeated_errors" | "no_progress" | "patch_entropy";
+    detectedAt: string;
+    iterationsElapsed: number;
+    estimatedIterations: number;
+}
+export interface ResumePoint {
+    taskId: string;
+    sessionId: string;
+    checkpointPath: string;
+    savedAt: string;
+}
+export interface ProjectExecutiveState {
+    projectId: string;
+    projectPath: string;
+    goals: ProjectGoal[];
+    milestones: ProjectMilestone[];
+    activeTasks: string[];
+    stalledTasks: StalledTask[];
+    resumePoints: ResumePoint[];
+    updatedAt: string;
+}
+export interface ProjectExecutiveConfig {
+    /** defaults to ~/.yuan/projects/ */
+    storageDir?: string;
+}
+export declare class ProjectExecutive extends EventEmitter {
+    private state;
+    private storagePath;
+    constructor(projectPath: string, config?: ProjectExecutiveConfig);
+    private persist;
+    private emitStateUpdate;
+    /**
+     * Add a new goal. Returns the created goal. Emits agent:project_state_update.
+     */
+    addGoal(description: string, strategy: GoalStrategy, estimatedIterations?: number): ProjectGoal;
+    /**
+     * Mark a goal as completed or abandoned. Emits agent:project_state_update.
+     */
+    completeGoal(goalId: string, status: "completed" | "abandoned"): void;
+    /** Add a milestone to a goal. */
+    addMilestone(goalId: string, description: string, targetIteration: number): ProjectMilestone;
+    /**
+     * Check and possibly mark a milestone as reached.
+     * Emits agent:milestone_reached if reached.
+     */
+    checkMilestone(milestoneId: string, currentIteration: number): boolean;
+    /** Register a stalled task. Emits agent:task_stalled. */
+    recordStall(taskId: string, reason: StalledTask["stallReason"], iterationsElapsed: number, estimatedIterations: number): void;
+    /** Clear a stall (task resumed or resolved). */
+    clearStall(taskId: string): void;
+    /** Save a resume point for a task. */
+    addResumePoint(taskId: string, sessionId: string, checkpointPath: string): void;
+    /** Mark a task as active. */
+    activateTask(taskId: string): void;
+    /** Mark a task as no longer active. */
+    deactivateTask(taskId: string): void;
+    /** Get current state snapshot. */
+    getState(): ProjectExecutiveState;
+}
+//# sourceMappingURL=project-executive.d.ts.map

package/dist/project-executive.d.ts.map

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

package/dist/project-executive.js

@@ -0,0 +1,223 @@
+/**
+ * @module project-executive
+ * @description Long-Horizon Project Executive — manages project-level goals, milestones,
+ * stalled task detection, and resume points.
+ *
+ * Storage: ~/.yuan/projects/{projectId}/executive.json
+ * projectId = stable 8-char hash of projectPath
+ *
+ * Design:
+ * - Event-driven observer ONLY — does NOT mutate agent-loop state
+ * - Reads from TaskMemory but does not write to it
+ * - All persistence is atomic (.tmp + renameSync)
+ * - Emits structured events for all state transitions
+ */
+import { EventEmitter } from "node:events";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+// ─── Helpers ───────────────────────────────────────────────────────────────
+function makeProjectId(projectPath) {
+    return Buffer.from(projectPath)
+        .toString("base64")
+        .replace(/[^a-z0-9]/gi, "")
+        .slice(0, 8);
+}
+function makeId() {
+    return Math.random().toString(36).slice(2, 10) + Date.now().toString(36);
+}
+function atomicWrite(filePath, data) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const tmp = filePath + ".tmp";
+    writeFileSync(tmp, data, "utf8");
+    renameSync(tmp, filePath);
+}
+function emptyState(projectId, projectPath) {
+    return {
+        projectId,
+        projectPath,
+        goals: [],
+        milestones: [],
+        activeTasks: [],
+        stalledTasks: [],
+        resumePoints: [],
+        updatedAt: new Date().toISOString(),
+    };
+}
+// ─── ProjectExecutive ──────────────────────────────────────────────────────
+export class ProjectExecutive extends EventEmitter {
+    state;
+    storagePath;
+    constructor(projectPath, config) {
+        super();
+        const projectId = makeProjectId(projectPath);
+        const storageDir = config?.storageDir ?? join(homedir(), ".yuan", "projects");
+        this.storagePath = join(storageDir, projectId, "executive.json");
+        // Load existing state or create empty
+        if (existsSync(this.storagePath)) {
+            try {
+                const raw = readFileSync(this.storagePath, "utf8");
+                this.state = JSON.parse(raw);
+            }
+            catch {
+                this.state = emptyState(projectId, projectPath);
+            }
+        }
+        else {
+            this.state = emptyState(projectId, projectPath);
+        }
+    }
+    // ── Persistence ──────────────────────────────────────────────────────────
+    persist() {
+        this.state.updatedAt = new Date().toISOString();
+        atomicWrite(this.storagePath, JSON.stringify(this.state, null, 2));
+    }
+    emitStateUpdate() {
+        this.emit("event", {
+            kind: "agent:project_state_update",
+            projectId: this.state.projectId,
+            goals: this.state.goals.length,
+            activeTasks: this.state.activeTasks.length,
+            stalledTasks: this.state.stalledTasks.length,
+            timestamp: Date.now(),
+        });
+    }
+    // ── Goals ─────────────────────────────────────────────────────────────────
+    /**
+     * Add a new goal. Returns the created goal. Emits agent:project_state_update.
+     */
+    addGoal(description, strategy, estimatedIterations = 20) {
+        const goal = {
+            id: makeId(),
+            description,
+            strategy,
+            status: "active",
+            childTaskIds: [],
+            estimatedIterations,
+            createdAt: new Date().toISOString(),
+        };
+        this.state.goals.push(goal);
+        this.persist();
+        this.emitStateUpdate();
+        return goal;
+    }
+    /**
+     * Mark a goal as completed or abandoned. Emits agent:project_state_update.
+     */
+    completeGoal(goalId, status) {
+        const goal = this.state.goals.find((g) => g.id === goalId);
+        if (!goal)
+            return;
+        goal.status = status;
+        goal.completedAt = new Date().toISOString();
+        this.persist();
+        this.emitStateUpdate();
+    }
+    // ── Milestones ────────────────────────────────────────────────────────────
+    /** Add a milestone to a goal. */
+    addMilestone(goalId, description, targetIteration) {
+        const milestone = {
+            id: makeId(),
+            description,
+            goalId,
+            targetIteration,
+            status: "pending",
+        };
+        this.state.milestones.push(milestone);
+        this.persist();
+        return milestone;
+    }
+    /**
+     * Check and possibly mark a milestone as reached.
+     * Emits agent:milestone_reached if reached.
+     */
+    checkMilestone(milestoneId, currentIteration) {
+        const ms = this.state.milestones.find((m) => m.id === milestoneId);
+        if (!ms || ms.status !== "pending")
+            return false;
+        if (currentIteration >= ms.targetIteration) {
+            ms.status = "reached";
+            ms.reachedAt = new Date().toISOString();
+            this.persist();
+            this.emit("event", {
+                kind: "agent:milestone_reached",
+                milestoneId: ms.id,
+                goalId: ms.goalId,
+                description: ms.description,
+                timestamp: Date.now(),
+            });
+            return true;
+        }
+        return false;
+    }
+    // ── Stall Tracking ────────────────────────────────────────────────────────
+    /** Register a stalled task. Emits agent:task_stalled. */
+    recordStall(taskId, reason, iterationsElapsed, estimatedIterations) {
+        // Avoid duplicates
+        const existing = this.state.stalledTasks.find((s) => s.taskId === taskId);
+        if (existing) {
+            existing.stallReason = reason;
+            existing.detectedAt = new Date().toISOString();
+            existing.iterationsElapsed = iterationsElapsed;
+            existing.estimatedIterations = estimatedIterations;
+        }
+        else {
+            this.state.stalledTasks.push({
+                taskId,
+                stallReason: reason,
+                detectedAt: new Date().toISOString(),
+                iterationsElapsed,
+                estimatedIterations,
+            });
+        }
+        this.persist();
+        this.emit("event", {
+            kind: "agent:task_stalled",
+            taskId,
+            stallReason: reason,
+            iterationsElapsed,
+            estimatedIterations,
+            timestamp: Date.now(),
+        });
+    }
+    /** Clear a stall (task resumed or resolved). */
+    clearStall(taskId) {
+        this.state.stalledTasks = this.state.stalledTasks.filter((s) => s.taskId !== taskId);
+        this.persist();
+    }
+    // ── Resume Points ─────────────────────────────────────────────────────────
+    /** Save a resume point for a task. */
+    addResumePoint(taskId, sessionId, checkpointPath) {
+        // Replace existing resume point for same taskId
+        this.state.resumePoints = this.state.resumePoints.filter((r) => r.taskId !== taskId);
+        this.state.resumePoints.push({
+            taskId,
+            sessionId,
+            checkpointPath,
+            savedAt: new Date().toISOString(),
+        });
+        this.persist();
+    }
+    // ── Active Task Tracking ──────────────────────────────────────────────────
+    /** Mark a task as active. */
+    activateTask(taskId) {
+        if (!this.state.activeTasks.includes(taskId)) {
+            this.state.activeTasks.push(taskId);
+            this.persist();
+        }
+    }
+    /** Mark a task as no longer active. */
+    deactivateTask(taskId) {
+        this.state.activeTasks = this.state.activeTasks.filter((id) => id !== taskId);
+        this.persist();
+    }
+    // ── State Access ──────────────────────────────────────────────────────────
+    /** Get current state snapshot. */
+    getState() {
+        return JSON.parse(JSON.stringify(this.state));
+    }
+}
+//# sourceMappingURL=project-executive.js.map

package/dist/project-executive.js.map

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

package/dist/research-loop.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @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";
+export interface ResearchHypothesis {
+    id: string;
+    statement: string;
+    confidence: number;
+    supportingEvidence: string[];
+    contradictingEvidence: string[];
+    status: "active" | "confirmed" | "rejected" | "inconclusive";
+}
+export interface ResearchSession {
+    id: string;
+    problem: string;
+    hypotheses: ResearchHypothesis[];
+    searchResults: Array<{
+        query: string;
+        source: "code" | "docs" | "web" | "issues";
+        snippets: string[];
+        timestamp: string;
+    }>;
+    conclusion: string;
+    recommendedStrategy: string;
+    confidence: number;
+    iterations: number;
+    startedAt: string;
+    completedAt?: string;
+}
+export interface ResearchLoopConfig {
+    /** Max iterations per research session. Default: 5 */
+    maxIterations?: number;
+    /** Stop early when any hypothesis reaches this confidence. Default: 0.75 */
+    minConfidenceToStop?: number;
+    /** Directory to store sessions.json. Default: ~/.yuan/research/ */
+    storageDir?: string;
+}
+export declare class ResearchLoop extends EventEmitter {
+    private readonly maxIterations;
+    private readonly minConfidenceToStop;
+    private readonly storageDir;
+    private sessions;
+    constructor(config?: ResearchLoopConfig);
+    /**
+     * 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
+     */
+    research(problem: string, searchFn: (query: string, source: "code" | "docs") => Promise<string[]>, sessionId?: string): Promise<ResearchSession>;
+    /**
+     * Return all research sessions loaded from storage (+ any run in this instance).
+     */
+    getSessions(): ResearchSession[];
+    /**
+     * 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: string): ResearchSession | null;
+}
+//# sourceMappingURL=research-loop.d.ts.map

package/dist/research-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-loop.d.ts","sourceRoot":"","sources":["../src/research-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAc3C,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,MAAM,EAAE,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,CAAC;CAC9D;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,aAAa,EAAE,KAAK,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;QAC3C,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC,CAAC;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA8OD,qBAAa,YAAa,SAAQ,YAAY;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAoB;gBAExB,MAAM,GAAE,kBAAuB;IAQ3C;;;;;;;;OAQG;IACG,QAAQ,CACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,EACvE,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC;IAgH3B;;OAEG;IACH,WAAW,IAAI,eAAe,EAAE;IAIhC;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;CAetD"}