clementine-agent 1.0.0

package/dist/agent/source-mods.js

@@ -0,0 +1,230 @@
+/**
+ * Clementine TypeScript — Source Modification Registry.
+ *
+ * Tracks self-improve source edits in ~/.clementine/ (not in git).
+ * When `clementine update` pulls new code, the reconciliation step
+ * re-applies active modifications that are still needed.
+ *
+ * This decouples user-local improvements from the upstream repo,
+ * so `git pull` is always clean and user customizations survive.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, rmSync, } from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+import { SOURCE_MODS_DIR } from '../config.js';
+const logger = pino({ name: 'clementine.source-mods' });
+// ── Registry Operations ──────────────────────────────────────────────
+function ensureDir() {
+    if (!existsSync(SOURCE_MODS_DIR)) {
+        mkdirSync(SOURCE_MODS_DIR, { recursive: true });
+    }
+}
+/** Record a new source modification with before/after file snapshots. */
+export function recordSourceMod(id, files, opts) {
+    ensureDir();
+    const record = {
+        id,
+        files: files.map(f => f.relativePath),
+        reason: opts.reason,
+        description: opts.description,
+        experimentId: opts.experimentId,
+        appliedAt: new Date().toISOString(),
+        status: 'active',
+    };
+    // Write metadata
+    writeFileSync(path.join(SOURCE_MODS_DIR, `${id}.json`), JSON.stringify(record, null, 2));
+    // Write before/after snapshots
+    for (const file of files) {
+        const beforeDir = path.join(SOURCE_MODS_DIR, `${id}.before`);
+        const afterDir = path.join(SOURCE_MODS_DIR, `${id}.after`);
+        mkdirSync(path.join(beforeDir, path.dirname(file.relativePath)), { recursive: true });
+        mkdirSync(path.join(afterDir, path.dirname(file.relativePath)), { recursive: true });
+        writeFileSync(path.join(beforeDir, file.relativePath), file.beforeContent);
+        writeFileSync(path.join(afterDir, file.relativePath), file.afterContent);
+    }
+    logger.info({ id, files: record.files, reason: opts.reason }, 'Source modification recorded');
+}
+/** Load all source mod records. */
+export function loadSourceMods() {
+    ensureDir();
+    return readdirSync(SOURCE_MODS_DIR)
+        .filter(f => f.endsWith('.json'))
+        .map(f => {
+        try {
+            return JSON.parse(readFileSync(path.join(SOURCE_MODS_DIR, f), 'utf-8'));
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter(Boolean);
+}
+/** Load only active mods. */
+export function loadActiveSourceMods() {
+    return loadSourceMods().filter(m => m.status === 'active');
+}
+/** Update a mod's status. */
+export function updateModStatus(id, status) {
+    const filePath = path.join(SOURCE_MODS_DIR, `${id}.json`);
+    if (!existsSync(filePath))
+        return;
+    const record = JSON.parse(readFileSync(filePath, 'utf-8'));
+    record.status = status;
+    writeFileSync(filePath, JSON.stringify(record, null, 2));
+}
+/** Remove a mod and its snapshots entirely. */
+export function removeSourceMod(id) {
+    const jsonPath = path.join(SOURCE_MODS_DIR, `${id}.json`);
+    const beforeDir = path.join(SOURCE_MODS_DIR, `${id}.before`);
+    const afterDir = path.join(SOURCE_MODS_DIR, `${id}.after`);
+    try {
+        if (existsSync(jsonPath))
+            rmSync(jsonPath);
+    }
+    catch { /* best effort */ }
+    try {
+        if (existsSync(beforeDir))
+            rmSync(beforeDir, { recursive: true });
+    }
+    catch { /* best effort */ }
+    try {
+        if (existsSync(afterDir))
+            rmSync(afterDir, { recursive: true });
+    }
+    catch { /* best effort */ }
+}
+/** Read the stored "after" content for a mod's file. */
+export function readModAfterContent(id, relativePath) {
+    const filePath = path.join(SOURCE_MODS_DIR, `${id}.after`, relativePath);
+    if (!existsSync(filePath))
+        return null;
+    return readFileSync(filePath, 'utf-8');
+}
+/** Read the stored "before" content for a mod's file (for rollback). */
+export function readModBeforeContent(id, relativePath) {
+    const filePath = path.join(SOURCE_MODS_DIR, `${id}.before`, relativePath);
+    if (!existsSync(filePath))
+        return null;
+    return readFileSync(filePath, 'utf-8');
+}
+// ── Rollback ─────────────────────────────────────────────────────────
+/** Rollback a source mod by restoring the "before" snapshots. */
+export function rollbackSourceMod(id, pkgDir) {
+    const record = loadSourceMods().find(m => m.id === id);
+    if (!record)
+        return false;
+    for (const relativePath of record.files) {
+        const before = readModBeforeContent(id, relativePath);
+        if (before !== null) {
+            writeFileSync(path.join(pkgDir, relativePath), before);
+        }
+    }
+    updateModStatus(id, 'failed');
+    logger.info({ id }, 'Source modification rolled back');
+    return true;
+}
+// ── Reconciliation (post-update) ─────────────────────────────────────
+function fileHash(content) {
+    return createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+/**
+ * Reconcile active source mods after an upstream update.
+ *
+ * For each active mod:
+ * 1. If the current file already matches our "after" content → superseded
+ * 2. If the current file matches our "before" content → re-apply directly
+ * 3. If the current file is different from both → needs LLM reconciliation
+ *
+ * After re-applying, runs a typecheck. Failures get reverted.
+ */
+export function reconcileSourceMods(pkgDir) {
+    const result = {
+        reapplied: [],
+        superseded: [],
+        needsReconciliation: [],
+        failed: [],
+    };
+    const activeMods = loadActiveSourceMods();
+    if (activeMods.length === 0)
+        return result;
+    logger.info({ count: activeMods.length }, 'Reconciling source modifications after update');
+    for (const mod of activeMods) {
+        let modResult = 'needs-reconciliation';
+        // Check each file in the mod
+        const fileChecks = [];
+        for (const relativePath of mod.files) {
+            const currentPath = path.join(pkgDir, relativePath);
+            const currentContent = existsSync(currentPath) ? readFileSync(currentPath, 'utf-8') : '';
+            const afterContent = readModAfterContent(mod.id, relativePath);
+            const beforeContent = readModBeforeContent(mod.id, relativePath);
+            const currentHash = fileHash(currentContent);
+            const afterHash = afterContent ? fileHash(afterContent) : '';
+            const beforeHash = beforeContent ? fileHash(beforeContent) : '';
+            if (currentHash === afterHash) {
+                // Current file already has our changes (upstream included them)
+                fileChecks.push({ relativePath, action: 'superseded' });
+            }
+            else if (currentHash === beforeHash) {
+                // File is back to pre-mod state — upstream didn't change it, safe to re-apply
+                fileChecks.push({ relativePath, action: 'reapply' });
+            }
+            else {
+                // File changed upstream AND our mod is gone — needs intelligent merge
+                fileChecks.push({ relativePath, action: 'needs-reconciliation' });
+            }
+        }
+        // Determine overall mod action
+        const hasNeedsRecon = fileChecks.some(f => f.action === 'needs-reconciliation');
+        const allSuperseded = fileChecks.every(f => f.action === 'superseded');
+        if (allSuperseded) {
+            modResult = 'superseded';
+        }
+        else if (hasNeedsRecon) {
+            modResult = 'needs-reconciliation';
+        }
+        else {
+            modResult = 'reapply';
+        }
+        if (modResult === 'superseded') {
+            updateModStatus(mod.id, 'superseded');
+            result.superseded.push(mod.id);
+            logger.info({ id: mod.id, reason: mod.reason }, 'Source mod superseded by upstream');
+        }
+        else if (modResult === 'reapply') {
+            // Re-apply all files
+            for (const relativePath of mod.files) {
+                const afterContent = readModAfterContent(mod.id, relativePath);
+                if (afterContent) {
+                    writeFileSync(path.join(pkgDir, relativePath), afterContent);
+                }
+            }
+            result.reapplied.push(mod.id);
+            logger.info({ id: mod.id, reason: mod.reason }, 'Source mod re-applied after update');
+        }
+        else {
+            updateModStatus(mod.id, 'needs-reconciliation');
+            result.needsReconciliation.push(mod.id);
+            logger.info({ id: mod.id, reason: mod.reason }, 'Source mod needs LLM reconciliation');
+        }
+    }
+    // If we re-applied anything, typecheck
+    if (result.reapplied.length > 0) {
+        try {
+            const { execSync } = require('node:child_process');
+            execSync('./node_modules/.bin/tsc --noEmit', { cwd: pkgDir, stdio: 'pipe', timeout: 120_000 });
+            logger.info({ count: result.reapplied.length }, 'Typecheck passed after re-applying source mods');
+        }
+        catch {
+            // Typecheck failed — revert all re-applied mods
+            logger.warn('Typecheck failed after re-applying source mods — reverting');
+            for (const modId of result.reapplied) {
+                rollbackSourceMod(modId, pkgDir);
+            }
+            result.failed.push(...result.reapplied);
+            result.reapplied = [];
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=source-mods.js.map

package/dist/agent/source-preflight.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Clementine TypeScript — Worktree Preflight Validator.
+ *
+ * Validates proposed source changes in an isolated git worktree before
+ * they touch the live repo. Uses worktree isolation for safe validation.
+ */
+export interface PreflightResult {
+    success: boolean;
+    errors?: string[];
+}
+/**
+ * Validate proposed source changes in an isolated git worktree.
+ *
+ * 1. Create a detached worktree from HEAD
+ * 2. Symlink node_modules from the real tree
+ * 3. Write the changed .ts files into the worktree
+ * 4. Run `./node_modules/.bin/tsc --noEmit` to type-check
+ * 5. Return success/failure with compiler errors
+ * 6. Always clean up the worktree
+ */
+export declare function preflightSourceChange(pkgDir: string, changes: Array<{
+    relativePath: string;
+    content: string;
+}>): Promise<PreflightResult>;
+//# sourceMappingURL=source-preflight.d.ts.map

package/dist/agent/source-preflight.js

@@ -0,0 +1,100 @@
+/**
+ * Clementine TypeScript — Worktree Preflight Validator.
+ *
+ * Validates proposed source changes in an isolated git worktree before
+ * they touch the live repo. Uses worktree isolation for safe validation.
+ */
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, symlinkSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+import { STAGING_DIR } from '../config.js';
+const logger = pino({ name: 'clementine.source-preflight' });
+/**
+ * Validate proposed source changes in an isolated git worktree.
+ *
+ * 1. Create a detached worktree from HEAD
+ * 2. Symlink node_modules from the real tree
+ * 3. Write the changed .ts files into the worktree
+ * 4. Run `./node_modules/.bin/tsc --noEmit` to type-check
+ * 5. Return success/failure with compiler errors
+ * 6. Always clean up the worktree
+ */
+export async function preflightSourceChange(pkgDir, changes) {
+    const timestamp = Date.now();
+    const worktreePath = path.join(STAGING_DIR, `preflight-${timestamp}`);
+    // Ensure staging directory exists
+    if (!existsSync(STAGING_DIR)) {
+        mkdirSync(STAGING_DIR, { recursive: true });
+    }
+    try {
+        // 1. Create detached worktree from HEAD
+        logger.info({ worktreePath }, 'Creating preflight worktree');
+        execSync(`git worktree add --detach "${worktreePath}" HEAD`, {
+            cwd: pkgDir,
+            stdio: 'pipe',
+        });
+        // 2. Symlink node_modules from the real tree
+        const realModules = path.join(pkgDir, 'node_modules');
+        const worktreeModules = path.join(worktreePath, 'node_modules');
+        if (existsSync(realModules)) {
+            try {
+                symlinkSync(realModules, worktreeModules, 'junction');
+            }
+            catch {
+                // Fallback: copy if symlink fails (e.g., cross-device)
+                logger.warn('Symlink failed — copying node_modules');
+                execSync(`cp -r "${realModules}" "${worktreeModules}"`, { stdio: 'pipe' });
+            }
+        }
+        // 3. Write changed .ts files into the worktree
+        for (const change of changes) {
+            const targetFile = path.join(worktreePath, change.relativePath);
+            const targetDir = path.dirname(targetFile);
+            if (!existsSync(targetDir)) {
+                mkdirSync(targetDir, { recursive: true });
+            }
+            writeFileSync(targetFile, change.content);
+        }
+        // 4. Run tsc --noEmit to type-check
+        try {
+            execSync('./node_modules/.bin/tsc --noEmit', {
+                cwd: worktreePath,
+                stdio: 'pipe',
+                timeout: 60_000,
+            });
+            logger.info('Preflight compilation succeeded');
+            return { success: true };
+        }
+        catch (err) {
+            const stderr = err.stderr?.toString() ?? '';
+            const stdout = err.stdout?.toString() ?? '';
+            const output = (stderr + '\n' + stdout).trim();
+            const errors = output.split('\n').filter(Boolean);
+            logger.warn({ errorCount: errors.length }, 'Preflight compilation failed');
+            return { success: false, errors };
+        }
+    }
+    catch (err) {
+        logger.error({ err }, 'Preflight worktree setup failed');
+        return {
+            success: false,
+            errors: [`Worktree setup failed: ${String(err)}`],
+        };
+    }
+    finally {
+        // 6. Always clean up the worktree
+        try {
+            execSync(`git worktree remove --force "${worktreePath}"`, {
+                cwd: pkgDir,
+                stdio: 'pipe',
+            });
+            logger.info('Preflight worktree cleaned up');
+        }
+        catch {
+            // Best effort — worktree prune will catch it later
+            logger.warn({ worktreePath }, 'Failed to remove preflight worktree — will be pruned later');
+        }
+    }
+}
+//# sourceMappingURL=source-preflight.js.map

package/dist/agent/stall-guard.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Clementine TypeScript — StallGuard.
+ *
+ * Per-query stall detection and enforcement. Combines tool loop detection,
+ * metacognitive monitoring, and read-blocking into a single query-scoped
+ * instance. No global mutable state — concurrent queries get their own guard.
+ *
+ * Lifecycle:
+ *   1. Created before each SDK query
+ *   2. Passed to buildOptions() → canUseTool checks shouldBlockTool()
+ *   3. recordToolCall() called for each tool_use block in the stream
+ *   4. After query: detectPromiseWithoutAction() + getSummary() for cross-query nudges
+ */
+import { type MetacognitiveSignal, type MetacognitiveSummary } from './metacognition.js';
+export interface StallSummary {
+    metacognition: MetacognitiveSummary;
+    breakerActivated: boolean;
+    breakerReason: string;
+    toolCalls: string[];
+}
+export declare class StallGuard {
+    private loopDetector;
+    private metacog;
+    private breakerActive;
+    private breakerReason;
+    private toolCallLog;
+    /**
+     * Check if a tool should be blocked. Called from canUseTool.
+     * When the breaker is active, denies read-only tools to force the agent
+     * to either act (Write/Edit/Bash) or respond to the user.
+     */
+    shouldBlockTool(toolName: string): {
+        block: boolean;
+        message?: string;
+    };
+    /**
+     * Record a tool call. Runs loop detection and metacognition.
+     * Activates the breaker if either detector fires.
+     *
+     * If the breaker is already active and this is a read-only tool, it was
+     * denied by shouldBlockTool. Skip metacognition tracking for denied tools
+     * to prevent a feedback loop where denials inflate the consecutive-read
+     * counter (logs showed counter spiraling from 5 → 15 in milliseconds).
+     */
+    recordToolCall(toolName: string, input: Record<string, unknown>): void;
+    /**
+     * Record a tool result for the loop detector's poll-no-progress check.
+     */
+    recordToolResult(resultText: string): void;
+    /**
+     * Post-query: check if the response promises action without delivery.
+     */
+    detectPromiseWithoutAction(responseText: string): MetacognitiveSignal;
+    /**
+     * Get summary for logging and cross-query stall nudge decisions.
+     */
+    getSummary(): StallSummary;
+    /** Get tool call log for transcript auditing. */
+    getToolCalls(): string[];
+    private activate;
+}
+//# sourceMappingURL=stall-guard.d.ts.map

package/dist/agent/stall-guard.js

@@ -0,0 +1,109 @@
+/**
+ * Clementine TypeScript — StallGuard.
+ *
+ * Per-query stall detection and enforcement. Combines tool loop detection,
+ * metacognitive monitoring, and read-blocking into a single query-scoped
+ * instance. No global mutable state — concurrent queries get their own guard.
+ *
+ * Lifecycle:
+ *   1. Created before each SDK query
+ *   2. Passed to buildOptions() → canUseTool checks shouldBlockTool()
+ *   3. recordToolCall() called for each tool_use block in the stream
+ *   4. After query: detectPromiseWithoutAction() + getSummary() for cross-query nudges
+ */
+import { ToolLoopDetector } from './tool-loop-detector.js';
+import { MetacognitiveMonitor } from './metacognition.js';
+import pino from 'pino';
+const logger = pino({ name: 'clementine.stall-guard' });
+// Only block SDK read tools — MCP tools (memory_read, etc.) are intentionally
+// left unblocked to give the agent some information access while forced to act.
+const READ_ONLY_TOOLS = new Set(['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch']);
+// ── StallGuard ──────────────────────────────────────────────────────
+export class StallGuard {
+    loopDetector = new ToolLoopDetector();
+    metacog = new MetacognitiveMonitor();
+    breakerActive = false;
+    breakerReason = '';
+    toolCallLog = [];
+    /**
+     * Check if a tool should be blocked. Called from canUseTool.
+     * When the breaker is active, denies read-only tools to force the agent
+     * to either act (Write/Edit/Bash) or respond to the user.
+     */
+    shouldBlockTool(toolName) {
+        if (this.breakerActive && READ_ONLY_TOOLS.has(toolName)) {
+            return {
+                block: true,
+                message: `STALL BREAKER: You have been reading without acting for too long. ${this.breakerReason} ` +
+                    `STOP reading. Either perform a write/action tool call (Write, Edit, Bash, etc.) to complete the task, ` +
+                    `or respond to the user explaining what is blocking you. Do NOT call another read-only tool.`,
+            };
+        }
+        return { block: false };
+    }
+    /**
+     * Record a tool call. Runs loop detection and metacognition.
+     * Activates the breaker if either detector fires.
+     *
+     * If the breaker is already active and this is a read-only tool, it was
+     * denied by shouldBlockTool. Skip metacognition tracking for denied tools
+     * to prevent a feedback loop where denials inflate the consecutive-read
+     * counter (logs showed counter spiraling from 5 → 15 in milliseconds).
+     */
+    recordToolCall(toolName, input) {
+        const wasDenied = this.breakerActive && READ_ONLY_TOOLS.has(toolName);
+        // Tool loop detector
+        const loopCheck = this.loopDetector.recordCall(toolName, input);
+        if (loopCheck.verdict === 'block') {
+            logger.warn({ tool: toolName, ...loopCheck }, 'Tool loop — activating stall breaker');
+            this.activate(loopCheck.detail ?? 'Repetitive tool calls detected.');
+        }
+        // Metacognitive monitor — only hard-block on 'intervene'.
+        // 'warn' logs and drops confidence but doesn't activate the breaker,
+        // so the agent can still read during legitimate multi-file research.
+        if (!wasDenied) {
+            const mcSignal = this.metacog.recordToolCall(toolName, input);
+            if (mcSignal.type === 'intervene') {
+                logger.warn({ reason: mcSignal.reason }, `Metacognition intervene: ${mcSignal.guidance?.slice(0, 80)}`);
+                this.activate(mcSignal.guidance ?? 'Agent appears stuck.');
+            }
+            else if (mcSignal.type === 'warn') {
+                logger.info({ reason: mcSignal.reason }, `Metacognition warn: ${mcSignal.guidance?.slice(0, 80)}`);
+            }
+        }
+        // Audit trail
+        this.toolCallLog.push(`${wasDenied ? '✗' : ''}${toolName}(${JSON.stringify(input).slice(0, 200)})`);
+    }
+    /**
+     * Record a tool result for the loop detector's poll-no-progress check.
+     */
+    recordToolResult(resultText) {
+        this.loopDetector.recordResult(resultText);
+    }
+    /**
+     * Post-query: check if the response promises action without delivery.
+     */
+    detectPromiseWithoutAction(responseText) {
+        return this.metacog.detectPromiseWithoutAction(responseText, this.toolCallLog.length);
+    }
+    /**
+     * Get summary for logging and cross-query stall nudge decisions.
+     */
+    getSummary() {
+        return {
+            metacognition: this.metacog.getSummary(),
+            breakerActivated: this.breakerActive,
+            breakerReason: this.breakerReason,
+            toolCalls: [...this.toolCallLog],
+        };
+    }
+    /** Get tool call log for transcript auditing. */
+    getToolCalls() {
+        return [...this.toolCallLog];
+    }
+    activate(reason) {
+        this.breakerActive = true;
+        this.breakerReason = reason;
+    }
+}
+//# sourceMappingURL=stall-guard.js.map

package/dist/agent/strategic-planner.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Clementine TypeScript — Strategic Planner (Multi-Horizon Planning).
+ *
+ * Weekly reviews: synthesize daily plans + goal progress into accomplishments,
+ * missed targets, patterns, and recommendations.
+ *
+ * Monthly assessments: cross-reference weekly reviews with goal completion
+ * and self-improvement experiments. Proposes OKR-style goals.
+ *
+ * Plans are persisted to ~/.clementine/plans/weekly/ and monthly/.
+ */
+import type { DailyPlan } from '../types.js';
+export interface WeeklyReview {
+    weekId: string;
+    createdAt: string;
+    accomplishments: string[];
+    missedTargets: string[];
+    patterns: string[];
+    recommendations: string[];
+    goalProgress: Array<{
+        goalId: string;
+        title: string;
+        status: string;
+        noteCount: number;
+    }>;
+    summary: string;
+}
+export interface MonthlyAssessment {
+    monthId: string;
+    createdAt: string;
+    weeklyTrends: string[];
+    goalCompletionRate: number;
+    systemicIssues: string[];
+    proposedGoals: Array<{
+        title: string;
+        description: string;
+        priority: string;
+    }>;
+    summary: string;
+}
+export declare class StrategicPlanner {
+    constructor();
+    hasWeeklyReview(weekId?: string): boolean;
+    generateWeeklyReview(): Promise<WeeklyReview>;
+    private gatherWeeklyContext;
+    private callLlmForWeekly;
+    hasMonthlyAssessment(monthId?: string): boolean;
+    generateMonthlyAssessment(): Promise<MonthlyAssessment>;
+    private gatherMonthlyContext;
+    private callLlmForMonthly;
+    /**
+     * Check if today's daily plan aligns with active high-priority goals.
+     * Returns a warning string if misaligned, null if fine.
+     */
+    checkGoalPlanAlignment(dailyPlan: DailyPlan): string | null;
+    private loadRecentDailyPlans;
+    private loadActiveGoals;
+    private loadAllGoals;
+}
+//# sourceMappingURL=strategic-planner.d.ts.map