clementine-agent 1.0.0

package/dist/events/bus.js

@@ -0,0 +1,136 @@
+/**
+ * Clementine TypeScript — Event Bus.
+ *
+ * Typed pub/sub system for decoupling gateway lifecycle events from consumers.
+ * Plugins, logging, metrics, and UI can subscribe without modifying core code.
+ *
+ * Events are fire-and-forget (async handlers don't block the emitter).
+ * "before" events return a boolean — false cancels the operation.
+ */
+import pino from 'pino';
+const logger = pino({ name: 'clementine.events' });
+class EventBus {
+    listeners = new Map();
+    beforeHandlers = new Map();
+    /**
+     * Subscribe to an event. Handler is called asynchronously (fire-and-forget).
+     * Returns an unsubscribe function.
+     */
+    on(event, handler) {
+        const subs = this.listeners.get(event) ?? [];
+        const sub = { handler: handler, once: false };
+        subs.push(sub);
+        this.listeners.set(event, subs);
+        return () => {
+            const list = this.listeners.get(event);
+            if (list) {
+                const idx = list.indexOf(sub);
+                if (idx !== -1)
+                    list.splice(idx, 1);
+            }
+        };
+    }
+    /** Subscribe to an event, but only fire once. */
+    once(event, handler) {
+        const subs = this.listeners.get(event) ?? [];
+        const sub = { handler: handler, once: true };
+        subs.push(sub);
+        this.listeners.set(event, subs);
+        return () => {
+            const list = this.listeners.get(event);
+            if (list) {
+                const idx = list.indexOf(sub);
+                if (idx !== -1)
+                    list.splice(idx, 1);
+            }
+        };
+    }
+    /**
+     * Register a "before" handler that can cancel an operation.
+     * If any before handler returns false, the operation is cancelled.
+     */
+    before(event, handler) {
+        const handlers = this.beforeHandlers.get(event) ?? [];
+        const entry = { handler: handler, once: false };
+        handlers.push(entry);
+        this.beforeHandlers.set(event, handlers);
+        return () => {
+            const list = this.beforeHandlers.get(event);
+            if (list) {
+                const idx = list.findIndex(e => e === entry);
+                if (idx !== -1)
+                    list.splice(idx, 1);
+            }
+        };
+    }
+    /**
+     * Emit an event asynchronously. Handlers run in parallel, errors are logged but don't propagate.
+     */
+    emit(event, payload) {
+        const subs = this.listeners.get(event);
+        if (!subs || subs.length === 0)
+            return;
+        // Snapshot handlers and remove once-listeners
+        const handlers = [...subs];
+        for (let i = subs.length - 1; i >= 0; i--) {
+            if (subs[i].once)
+                subs.splice(i, 1);
+        }
+        for (const sub of handlers) {
+            try {
+                const result = sub.handler(payload);
+                if (result instanceof Promise) {
+                    result.catch(err => logger.warn({ err, event }, 'Event handler error'));
+                }
+            }
+            catch (err) {
+                logger.warn({ err, event }, 'Event handler error (sync)');
+            }
+        }
+    }
+    /**
+     * Run "before" handlers sequentially. Returns true if all pass, false if any cancels.
+     */
+    async emitBefore(event, payload) {
+        const handlers = this.beforeHandlers.get(event);
+        if (!handlers || handlers.length === 0)
+            return true;
+        for (const entry of [...handlers]) {
+            try {
+                const result = entry.handler(payload);
+                const allowed = result instanceof Promise ? await result : result;
+                if (!allowed) {
+                    logger.info({ event }, 'Operation cancelled by before handler');
+                    return false;
+                }
+            }
+            catch (err) {
+                logger.warn({ err, event }, 'Before handler error — allowing operation');
+            }
+            if (entry.once) {
+                const idx = handlers.indexOf(entry);
+                if (idx !== -1)
+                    handlers.splice(idx, 1);
+            }
+        }
+        return true;
+    }
+    /** Remove all listeners for an event, or all events if no event specified. */
+    clear(event) {
+        if (event) {
+            this.listeners.delete(event);
+            this.beforeHandlers.delete(event);
+        }
+        else {
+            this.listeners.clear();
+            this.beforeHandlers.clear();
+        }
+    }
+    /** Get count of listeners for an event (useful for debugging). */
+    listenerCount(event) {
+        return (this.listeners.get(event)?.length ?? 0) + (this.beforeHandlers.get(event)?.length ?? 0);
+    }
+}
+/** Singleton event bus — shared across the entire process. */
+export const events = new EventBus();
+//# sourceMappingURL=bus.js.map

package/dist/gateway/cron-scheduler.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Clementine TypeScript — Cron scheduler (autonomous execution).
+ *
+ * CronScheduler: precise scheduled tasks using node-cron
+ *
+ * Also contains shared parsers (parseCronJobs, parseAgentCronJobs, validateCronYaml),
+ * retry helpers, CronRunLog, and daily-note logging utilities used by both schedulers.
+ */
+import type { CronJobDefinition, CronRunEntry, SelfImproveConfig, SelfImproveExperiment, SelfImproveState, WorkflowDefinition } from '../types.js';
+import type { NotificationDispatcher } from './notifications.js';
+import type { Gateway } from './router.js';
+/** Local-time YYYY-MM-DD for daily note path. */
+export declare function todayISO(): string;
+/**
+ * Append a line to today's daily note under ## Interactions.
+ * Creates the section if it doesn't exist. Non-fatal — never throws.
+ */
+export declare function logToDailyNote(line: string): void;
+/**
+ * Parse cron job definitions from vault/00-System/CRON.md frontmatter.
+ * Used by both the in-process CronScheduler and the standalone CLI runner.
+ */
+export declare function parseCronJobs(): CronJobDefinition[];
+/**
+ * Parse cron jobs from agent-scoped CRON.md files.
+ * Scans each agent subdirectory for CRON.md, prefixes job names with agent slug.
+ */
+export declare function parseAgentCronJobs(agentsDir: string): CronJobDefinition[];
+/**
+ * Validate that a CRON.md string parses without YAML errors.
+ * Call this before writing to prevent corrupted files from crashing the daemon.
+ * Returns null on success, or the error message on failure.
+ */
+export declare function validateCronYaml(content: string): string | null;
+export declare function classifyError(err: unknown): 'transient' | 'permanent';
+/**
+ * Classify a TerminalReason from the SDK into a retry strategy.
+ * More precise than classifyError() which relies on regex.
+ */
+export declare function classifyTerminalReason(reason: string): 'transient' | 'permanent';
+/**
+ * JSONL-based per-job run log.  Auto-prunes to keep files under 2 MB
+ * and 2000 lines (whichever limit hits first).
+ */
+export declare class CronRunLog {
+    private readonly dir;
+    private static readonly MAX_BYTES;
+    private static readonly MAX_LINES;
+    constructor(baseDir?: string);
+    private logPath;
+    append(entry: CronRunEntry): void;
+    readRecent(jobName: string, count?: number): CronRunEntry[];
+    consecutiveErrors(jobName: string): number;
+    private maybePrune;
+}
+export declare class CronScheduler {
+    private gateway;
+    private dispatcher;
+    private jobs;
+    private disabledJobs;
+    private scheduledTasks;
+    private runningJobs;
+    private completedJobs;
+    private watching;
+    readonly runLog: CronRunLog;
+    private workflowDefs;
+    private workflowTasks;
+    private runningWorkflows;
+    private watchingWorkflows;
+    private triggerDir;
+    private goalTriggerDir;
+    private triggerTimer;
+    private statusChangeListeners;
+    constructor(gateway: Gateway, dispatcher: NotificationDispatcher);
+    /** Load job definitions from CRON.md and agent dirs without scheduling tasks. */
+    private loadJobDefinitions;
+    /** Register a listener that fires when system state changes (job start/finish, self-improve, etc). */
+    onStatusChange(cb: () => void): void;
+    private emitStatusChange;
+    start(): void;
+    stop(): void;
+    /** Watch CRON.md for changes and auto-reload jobs. */
+    private watchCronFile;
+    private unwatchCronFile;
+    /** Watch agents directory for cron/workflow changes and auto-reload. */
+    private watchingAgents;
+    private watchAgentsDir;
+    private unwatchAgentsDir;
+    reloadJobs(): void;
+    private runJob;
+    /**
+     * Log an advisor event to the events JSONL file for dashboard surfacing.
+     */
+    private logAdvisorEvent;
+    /**
+     * Check if an agent's recent cron reflections show consistently low quality.
+     * If the last N runs average below the threshold, auto-append a "lessons learned"
+     * section to the agent's profile. This is additive (not destructive) — it
+     * only appends insights, never overwrites the core agent prompt.
+     */
+    private checkAgentLearning;
+    runManual(jobName: string): Promise<string>;
+    /** Filter out cron responses that are truly empty or nothing-to-report. */
+    /** Strip internal reasoning/thinking prefixes from cron output before sending to Discord. */
+    private static stripThinkingPrefixes;
+    private static isCronNoise;
+    /** Format cron error messages for clean notifications. */
+    private static formatCronError;
+    listJobs(): string;
+    getJobNames(): string[];
+    getJob(jobName: string): CronJobDefinition | undefined;
+    isJobRunning(jobName: string): boolean;
+    getRunningJobs(): string[];
+    getRunningWorkflowNames(): string[];
+    /** Return all job definitions with enabled/disabled state for the status embed. */
+    getJobDefinitions(): Array<CronJobDefinition & {
+        active: boolean;
+    }>;
+    /** Get today's run stats: total runs, successes, failures (since local midnight). */
+    getTodayStats(): {
+        total: number;
+        ok: number;
+        errors: number;
+        skipped: number;
+    };
+    disableJob(jobName: string): string;
+    enableJob(jobName: string): string;
+    reloadWorkflows(): void;
+    private watchWorkflowDir;
+    private unwatchWorkflowDir;
+    /** Watch the triggers directory for MCP-initiated job runs and goal work sessions. */
+    private watchTriggers;
+    /** Process any pending trigger files and run the corresponding jobs. */
+    private processTriggers;
+    /** Process any pending goal work trigger files. Routes through the execution advisor. */
+    private processGoalTriggers;
+    /**
+     * Log goal work session outcome to a per-goal progress JSONL file.
+     * Creates the causal link: "action X was attempted for goal Y, result was Z."
+     */
+    private logGoalOutcome;
+    /**
+     * Apply non-destructive cron changes suggested by the daily planner.
+     * Only auto-applies suggestions that reference a high-priority goal with autoSchedule=true.
+     * Supports: 'add' (new job), 'enable', 'disable'. Does NOT support 'delete' or 'modify'.
+     */
+    applySuggestedCronChanges(suggestions: Array<{
+        job: string;
+        change: string;
+        reason: string;
+    }>): void;
+    runWorkflow(name: string, inputs?: Record<string, string>): Promise<string>;
+    getWorkflowNames(): string[];
+    getWorkflow(name: string): WorkflowDefinition | undefined;
+    isWorkflowRunning(name: string): boolean;
+    listWorkflows(): string;
+    runSelfImproveLoop(config?: Partial<SelfImproveConfig>, onProposal?: (experiment: SelfImproveExperiment) => Promise<void>): Promise<SelfImproveState>;
+    applySelfImproveChange(experimentId: string): Promise<string>;
+    denySelfImproveChange(experimentId: string): string;
+    getSelfImproveStatus(): SelfImproveState;
+    getSelfImproveHistory(limit?: number): SelfImproveExperiment[];
+    getSelfImprovePending(): Array<SelfImproveExperiment & {
+        before: string;
+    }>;
+}
+//# sourceMappingURL=cron-scheduler.d.ts.map