clementine-agent 1.0.0

package/dist/agent/profiles.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Clementine TypeScript — Agent profile management.
+ *
+ * Profiles are Markdown files with YAML frontmatter stored in
+ * vault/00-System/profiles/. Each profile defines a persona with its own
+ * tone, tool restrictions, security tier, and system prompt body.
+ *
+ * ProfileManager scans the directory, caches AgentProfile objects, and
+ * hot-reloads when files change (60-second TTL).
+ */
+import type { AgentProfile } from '../types.js';
+export declare class ProfileManager {
+    private dir;
+    private cache;
+    private cacheTime;
+    constructor(profilesDir: string);
+    private refreshIfStale;
+    private loadProfile;
+    get(slug: string): AgentProfile | null;
+    listAll(): AgentProfile[];
+}
+//# sourceMappingURL=profiles.d.ts.map

package/dist/agent/profiles.js

@@ -0,0 +1,91 @@
+/**
+ * Clementine TypeScript — Agent profile management.
+ *
+ * Profiles are Markdown files with YAML frontmatter stored in
+ * vault/00-System/profiles/. Each profile defines a persona with its own
+ * tone, tool restrictions, security tier, and system prompt body.
+ *
+ * ProfileManager scans the directory, caches AgentProfile objects, and
+ * hot-reloads when files change (60-second TTL).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+const CACHE_TTL_MS = 60_000;
+export class ProfileManager {
+    dir;
+    cache = new Map();
+    cacheTime = 0;
+    constructor(profilesDir) {
+        this.dir = profilesDir;
+    }
+    refreshIfStale() {
+        const now = Date.now();
+        if (now - this.cacheTime < CACHE_TTL_MS && this.cache.size > 0) {
+            return;
+        }
+        if (!fs.existsSync(this.dir)) {
+            this.cache.clear();
+            this.cacheTime = now;
+            return;
+        }
+        const profiles = new Map();
+        const files = fs.readdirSync(this.dir).filter((f) => f.endsWith('.md') && !f.startsWith('_')).sort();
+        for (const file of files) {
+            try {
+                const filePath = path.join(this.dir, file);
+                const profile = this.loadProfile(filePath, file);
+                const slug = file.replace(/\.md$/, '');
+                profiles.set(slug, profile);
+            }
+            catch {
+                // Skip malformed profile files
+            }
+        }
+        this.cache = profiles;
+        this.cacheTime = now;
+    }
+    loadProfile(filePath, fileName) {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const { data: meta, content } = matter(raw);
+        const slug = fileName.replace(/\.md$/, '');
+        // Cap tier at 2 — profiles can never grant Tier 3
+        const tier = Math.min(Number(meta.tier ?? 1), 2);
+        // Parse team-specific frontmatter
+        let team;
+        const channelName = Array.isArray(meta.channelName)
+            ? meta.channelName.map(String).filter(Boolean)
+            : meta.channelName ? String(meta.channelName) : undefined;
+        const canMessage = Array.isArray(meta.canMessage)
+            ? meta.canMessage.map(String).filter(Boolean)
+            : [];
+        const allowedTools = Array.isArray(meta.allowedTools)
+            ? meta.allowedTools.map(String).filter(Boolean)
+            : undefined;
+        if (channelName && (typeof channelName === 'string' || channelName.length > 0)) {
+            // channels[] populated at runtime by the agent's own bot
+            const teamChat = meta.teamChat === true || meta.teamChat === 'true';
+            const respondToAll = meta.respondToAll === true || meta.respondToAll === 'true';
+            team = { channelName, channels: [], canMessage, allowedTools, teamChat, respondToAll: respondToAll || undefined };
+        }
+        return {
+            slug,
+            name: String(meta.name ?? slug.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase())),
+            tier,
+            description: String(meta.description ?? meta.role ?? ''),
+            systemPromptBody: content.trim(),
+            model: meta.model ? String(meta.model) : undefined,
+            avatar: meta.avatar ? String(meta.avatar) : undefined,
+            team,
+        };
+    }
+    get(slug) {
+        this.refreshIfStale();
+        return this.cache.get(slug) ?? null;
+    }
+    listAll() {
+        this.refreshIfStale();
+        return [...this.cache.values()];
+    }
+}
+//# sourceMappingURL=profiles.js.map

package/dist/agent/prompt-cache.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Clementine TypeScript — File-watcher cache for system prompt files.
+ *
+ * Pre-reads vault files and invalidates on fs change, avoiding 50-200ms
+ * of readFileSync + gray-matter parsing on every message.
+ */
+interface CacheEntry {
+    content: string;
+    data: Record<string, unknown>;
+}
+export declare class PromptCache {
+    private cache;
+    private watchers;
+    /** Get parsed file content. Loads and caches on first access. */
+    get(filePath: string): CacheEntry | null;
+    /** Start watching a file. Re-reads on change. */
+    watch(filePath: string): void;
+    private load;
+    /** Switch watched daily note path (call when date changes). */
+    swapWatch(oldPath: string, newPath: string): void;
+    dispose(): void;
+}
+export {};
+//# sourceMappingURL=prompt-cache.d.ts.map

package/dist/agent/prompt-cache.js

@@ -0,0 +1,68 @@
+/**
+ * Clementine TypeScript — File-watcher cache for system prompt files.
+ *
+ * Pre-reads vault files and invalidates on fs change, avoiding 50-200ms
+ * of readFileSync + gray-matter parsing on every message.
+ */
+import { readFileSync, existsSync, watch } from 'node:fs';
+import matter from 'gray-matter';
+export class PromptCache {
+    cache = new Map();
+    watchers = new Map();
+    /** Get parsed file content. Loads and caches on first access. */
+    get(filePath) {
+        if (this.cache.has(filePath))
+            return this.cache.get(filePath);
+        return this.load(filePath);
+    }
+    /** Start watching a file. Re-reads on change. */
+    watch(filePath) {
+        if (this.watchers.has(filePath))
+            return;
+        this.load(filePath);
+        if (!existsSync(filePath))
+            return;
+        try {
+            const w = watch(filePath, () => { this.cache.delete(filePath); });
+            w.unref(); // Don't keep daemon alive
+            this.watchers.set(filePath, w);
+        }
+        catch {
+            // Watch failed (e.g. file deleted between check and watch) — cache still works
+        }
+    }
+    load(filePath) {
+        if (!existsSync(filePath)) {
+            this.cache.set(filePath, null);
+            return null;
+        }
+        try {
+            const raw = readFileSync(filePath, 'utf-8');
+            const parsed = matter(raw);
+            const entry = { content: parsed.content, data: parsed.data };
+            this.cache.set(filePath, entry);
+            return entry;
+        }
+        catch {
+            this.cache.set(filePath, null);
+            return null;
+        }
+    }
+    /** Switch watched daily note path (call when date changes). */
+    swapWatch(oldPath, newPath) {
+        const w = this.watchers.get(oldPath);
+        if (w) {
+            w.close();
+            this.watchers.delete(oldPath);
+        }
+        this.cache.delete(oldPath);
+        this.watch(newPath);
+    }
+    dispose() {
+        for (const w of this.watchers.values())
+            w.close();
+        this.watchers.clear();
+        this.cache.clear();
+    }
+}
+//# sourceMappingURL=prompt-cache.js.map

package/dist/agent/prompt-evolver.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Clementine TypeScript — Adaptive Prompt Evolution.
+ *
+ * Evolves static cron prompts by enriching them with lessons from
+ * reflections, progress state, and goal context. Returns the enrichment
+ * string to be appended to the original prompt.
+ */
+interface PromptEvolutionContext {
+    jobName: string;
+    originalPrompt: string;
+    agentSlug?: string;
+}
+/**
+ * Evolve a static cron prompt by enriching it with lessons from reflections,
+ * progress state, and goal context. Returns the enrichment string (not the full prompt).
+ */
+export declare function evolvePrompt(ctx: PromptEvolutionContext): string;
+/**
+ * Log a strategy observation after a cron run completes.
+ * Called by the cron scheduler to track which approaches work/fail.
+ */
+export declare function logStrategyObservation(jobName: string, observation: {
+    toolsUsed: string[];
+    quality: number;
+    status: 'ok' | 'error';
+}): void;
+export {};
+//# sourceMappingURL=prompt-evolver.d.ts.map

package/dist/agent/prompt-evolver.js

@@ -0,0 +1,279 @@
+/**
+ * Clementine TypeScript — Adaptive Prompt Evolution.
+ *
+ * Evolves static cron prompts by enriching them with lessons from
+ * reflections, progress state, and goal context. Returns the enrichment
+ * string to be appended to the original prompt.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+import { BASE_DIR, CRON_REFLECTIONS_DIR, CRON_PROGRESS_DIR, GOALS_DIR } from '../config.js';
+const logger = pino({ name: 'clementine.prompt-evolver' });
+/**
+ * Evolve a static cron prompt by enriching it with lessons from reflections,
+ * progress state, and goal context. Returns the enrichment string (not the full prompt).
+ */
+export function evolvePrompt(ctx) {
+    const parts = [];
+    try {
+        const reflectionLessons = extractReflectionLessons(ctx.jobName);
+        if (reflectionLessons)
+            parts.push(reflectionLessons);
+    }
+    catch (err) {
+        logger.debug({ err, job: ctx.jobName }, 'Failed to extract reflection lessons');
+    }
+    try {
+        const strategyInsights = extractStrategyInsights(ctx.jobName);
+        if (strategyInsights)
+            parts.push(strategyInsights);
+    }
+    catch (err) {
+        logger.debug({ err, job: ctx.jobName }, 'Failed to extract strategy insights');
+    }
+    try {
+        const progressInsights = extractProgressInsights(ctx.jobName);
+        if (progressInsights)
+            parts.push(progressInsights);
+    }
+    catch (err) {
+        logger.debug({ err, job: ctx.jobName }, 'Failed to extract progress insights');
+    }
+    try {
+        const goalGuidance = extractGoalGuidance(ctx.jobName);
+        if (goalGuidance)
+            parts.push(goalGuidance);
+    }
+    catch (err) {
+        logger.debug({ err, job: ctx.jobName }, 'Failed to extract goal guidance');
+    }
+    return parts.join('\n\n');
+}
+/**
+ * Log a strategy observation after a cron run completes.
+ * Called by the cron scheduler to track which approaches work/fail.
+ */
+export function logStrategyObservation(jobName, observation) {
+    try {
+        const strategyDir = path.join(BASE_DIR, 'cron', 'strategies');
+        mkdirSync(strategyDir, { recursive: true });
+        const safe = jobName.replace(/[^a-zA-Z0-9_-]/g, '_');
+        const logFile = path.join(strategyDir, `${safe}.strategy.jsonl`);
+        appendFileSync(logFile, JSON.stringify({
+            timestamp: new Date().toISOString(),
+            toolsUsed: observation.toolsUsed.slice(0, 20),
+            quality: observation.quality,
+            status: observation.status,
+        }) + '\n');
+    }
+    catch {
+        // non-fatal
+    }
+}
+/**
+ * Extract lessons from past reflections where quality was low or gaps were noted.
+ * Deduplicates gap strings and formats them as guidance.
+ */
+function extractReflectionLessons(jobName) {
+    if (!existsSync(CRON_REFLECTIONS_DIR))
+        return null;
+    const safe = jobName.replace(/[^a-zA-Z0-9_-]/g, '_');
+    const reflectionFile = path.join(CRON_REFLECTIONS_DIR, `${safe}.jsonl`);
+    if (!existsSync(reflectionFile))
+        return null;
+    try {
+        const lines = readFileSync(reflectionFile, 'utf-8').trim().split('\n').filter(Boolean);
+        const recent = lines.slice(-10);
+        const gaps = new Set();
+        const commNotes = [];
+        for (const line of recent) {
+            try {
+                const entry = JSON.parse(line);
+                if (entry.quality < 3 && entry.gap) {
+                    gaps.add(entry.gap.trim());
+                }
+                if (entry.commNote) {
+                    commNotes.push(entry.commNote.trim());
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        if (gaps.size === 0 && commNotes.length === 0)
+            return null;
+        const parts = ['## Lessons from Previous Runs', 'Based on past performance reviews:'];
+        if (gaps.size > 0) {
+            for (const gap of gaps) {
+                parts.push(`- ${gap}`);
+            }
+            parts.push('Avoid these pitfalls in this run.');
+        }
+        if (commNotes.length > 0) {
+            parts.push('Communication notes:');
+            for (const note of commNotes.slice(-3)) {
+                parts.push(`- ${note}`);
+            }
+        }
+        return parts.join('\n');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extract strategy insights by correlating tool usage patterns with quality scores.
+ * Identifies which approaches (tool combinations) tend to succeed vs. fail.
+ */
+function extractStrategyInsights(jobName) {
+    const strategyDir = path.join(BASE_DIR, 'cron', 'strategies');
+    const safe = jobName.replace(/[^a-zA-Z0-9_-]/g, '_');
+    const logFile = path.join(strategyDir, `${safe}.strategy.jsonl`);
+    if (!existsSync(logFile))
+        return null;
+    try {
+        const lines = readFileSync(logFile, 'utf-8').trim().split('\n').filter(Boolean);
+        if (lines.length < 3)
+            return null; // need enough data
+        const recent = lines.slice(-15);
+        // Tally quality by top tool used
+        const toolStats = new Map();
+        for (const line of recent) {
+            try {
+                const entry = JSON.parse(line);
+                const topTools = (entry.toolsUsed ?? []).slice(0, 3);
+                const key = topTools.sort().join('+') || 'no-tools';
+                const stats = toolStats.get(key) ?? { total: 0, successCount: 0, qualitySum: 0 };
+                stats.total++;
+                if (entry.status === 'ok' && entry.quality >= 3)
+                    stats.successCount++;
+                stats.qualitySum += entry.quality ?? 3;
+                toolStats.set(key, stats);
+            }
+            catch {
+                continue;
+            }
+        }
+        if (toolStats.size === 0)
+            return null;
+        // Find best and worst approaches
+        const ranked = [...toolStats.entries()]
+            .filter(([, s]) => s.total >= 2)
+            .map(([approach, s]) => ({
+            approach,
+            successRate: s.successCount / s.total,
+            avgQuality: s.qualitySum / s.total,
+            total: s.total,
+        }))
+            .sort((a, b) => b.avgQuality - a.avgQuality);
+        if (ranked.length === 0)
+            return null;
+        const parts = ['## Strategy Insights'];
+        const best = ranked[0];
+        if (best.successRate >= 0.7) {
+            parts.push(`Recommended approach: **${best.approach}** (${Math.round(best.successRate * 100)}% success rate over ${best.total} runs, avg quality: ${best.avgQuality.toFixed(1)})`);
+        }
+        const worst = ranked[ranked.length - 1];
+        if (ranked.length > 1 && worst.successRate < 0.5) {
+            parts.push(`Avoid: **${worst.approach}** (${Math.round(worst.successRate * 100)}% success rate — consider alternative tools)`);
+        }
+        return parts.length > 1 ? parts.join('\n') : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extract insights from progress history — what's been done and what remains.
+ */
+function extractProgressInsights(jobName) {
+    if (!existsSync(CRON_PROGRESS_DIR))
+        return null;
+    const safe = jobName.replace(/[^a-zA-Z0-9_-]/g, '_');
+    const progressFile = path.join(CRON_PROGRESS_DIR, `${safe}.json`);
+    if (!existsSync(progressFile))
+        return null;
+    try {
+        const progress = JSON.parse(readFileSync(progressFile, 'utf-8'));
+        const parts = ['## Progress Continuity'];
+        if (progress.completedItems?.length > 0) {
+            const recentCompleted = progress.completedItems.slice(-5);
+            parts.push(`Recently completed (${progress.completedItems.length} total):`);
+            for (const item of recentCompleted) {
+                parts.push(`- Done: ${item}`);
+            }
+        }
+        if (progress.pendingItems?.length > 0) {
+            parts.push(`Still pending (${progress.pendingItems.length}):`);
+            for (const item of progress.pendingItems.slice(0, 5)) {
+                parts.push(`- TODO: ${item}`);
+            }
+        }
+        if (progress.notes) {
+            parts.push(`Previous notes: ${progress.notes.slice(0, 300)}`);
+        }
+        if (parts.length <= 1)
+            return null;
+        return parts.join('\n');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Find goals that reference this cron job and inject alignment guidance.
+ */
+function extractGoalGuidance(jobName) {
+    if (!existsSync(GOALS_DIR))
+        return null;
+    try {
+        const files = readdirSync(GOALS_DIR).filter(f => f.endsWith('.json'));
+        const linkedGoals = [];
+        for (const f of files) {
+            try {
+                const goal = JSON.parse(readFileSync(path.join(GOALS_DIR, f), 'utf-8'));
+                if (goal.status !== 'active')
+                    continue;
+                if (goal.linkedCronJobs?.includes(jobName)) {
+                    linkedGoals.push(goal);
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        if (linkedGoals.length === 0)
+            return null;
+        const parts = ['## Goal Alignment'];
+        for (const goal of linkedGoals) {
+            parts.push(`This job contributes to goal: "${goal.title}" (${goal.priority} priority)`);
+            if (goal.nextActions?.length) {
+                parts.push('Goal next actions to consider:');
+                for (const action of goal.nextActions.slice(0, 3)) {
+                    parts.push(`- ${action}`);
+                }
+            }
+            if (goal.blockers?.length) {
+                parts.push('Known blockers:');
+                for (const blocker of goal.blockers) {
+                    parts.push(`- Blocker: ${blocker}`);
+                }
+            }
+            if (goal.targetDate) {
+                const daysLeft = Math.floor((new Date(goal.targetDate).getTime() - Date.now()) / 86_400_000);
+                if (daysLeft <= 7 && daysLeft >= 0) {
+                    parts.push(`Target date approaching: ${goal.targetDate} (${daysLeft} day(s) left)`);
+                }
+                else if (daysLeft < 0) {
+                    parts.push(`Target date OVERDUE: ${goal.targetDate} (${Math.abs(daysLeft)} day(s) past)`);
+                }
+            }
+        }
+        return parts.join('\n');
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=prompt-evolver.js.map

package/dist/agent/role-scaffolds.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Clementine TypeScript — Role scaffolding templates.
+ *
+ * When an agent is created with a role template, these generate the full
+ * working directory: CRON.md, playbook, sequence definitions, and email
+ * writing guidelines. This is what turns an empty agent into a working employee.
+ */
+export interface RoleScaffold {
+    /** CRON.md content — the agent's autonomous job definitions. */
+    cronMd: string;
+    /** Playbook/ICP file — the agent's knowledge base for decision-making. */
+    playbook: string;
+    /** Sequence definitions — multi-step cadence templates. */
+    sequences?: string;
+}
+/**
+ * Generate scaffolding files for an SDR agent.
+ * @param agentName — Display name (e.g., "Alex the SDR")
+ * @param agentSlug — URL-safe slug (e.g., "alex-the-sdr")
+ */
+export declare function scaffoldSdr(agentName: string, agentSlug: string): RoleScaffold;
+/**
+ * Generate scaffolding files for a Researcher agent.
+ */
+export declare function scaffoldResearcher(agentName: string, agentSlug: string): RoleScaffold;
+/** Get scaffold generator for a role, or null if no scaffold exists. */
+export declare function getScaffoldForRole(role: string): ((name: string, slug: string) => RoleScaffold) | null;
+//# sourceMappingURL=role-scaffolds.d.ts.map