clementine-agent 1.0.95 → 1.0.96

package/dist/agent/prompt-overrides/loader.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Prompt Overrides — loader.
+ *
+ * Reads markdown files from ~/.clementine/prompt-overrides/ and serves
+ * scope-resolved override text for a given (jobName, agentSlug). Hot-reloads
+ * via fs.watch (debounced).
+ *
+ * No package builtins — these are purely user/LLM authored. The directory
+ * is created on first load so users have an obvious empty home for overrides.
+ */
+import type { PromptOverride } from './types.js';
+export interface LoaderOptions {
+    baseDir?: string;
+}
+export declare function loadPromptOverrides(opts?: LoaderOptions): PromptOverride[];
+export declare function getLoadedOverrides(): PromptOverride[];
+/**
+ * Resolve overrides applicable to a given job: global + agent (if agentSlug
+ * matches) + job (if jobName matches), sorted by priority ascending and
+ * concatenated into a single string. Empty if no overrides apply.
+ */
+export declare function loadPromptOverridesForJob(jobName: string, agentSlug?: string, opts?: LoaderOptions): string;
+/** Install fs.watch on the overrides directory tree. Safe to call multiple times. */
+export declare function watchPromptOverrides(opts?: LoaderOptions): void;
+/** Test-only: clear cached state. */
+export declare function _resetLoaderState(): void;
+//# sourceMappingURL=loader.d.ts.map

package/dist/agent/prompt-overrides/loader.js

@@ -0,0 +1,160 @@
+/**
+ * Prompt Overrides — loader.
+ *
+ * Reads markdown files from ~/.clementine/prompt-overrides/ and serves
+ * scope-resolved override text for a given (jobName, agentSlug). Hot-reloads
+ * via fs.watch (debounced).
+ *
+ * No package builtins — these are purely user/LLM authored. The directory
+ * is created on first load so users have an obvious empty home for overrides.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, watch as fsWatch } from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+import matter from 'gray-matter';
+import { BASE_DIR } from '../../config.js';
+const logger = pino({ name: 'clementine.prompt-overrides' });
+function rootDir(baseDir) {
+    return path.join(baseDir, 'prompt-overrides');
+}
+// ── State ────────────────────────────────────────────────────────────
+let cached = [];
+let watcherInstalled = false;
+let watchDebounce = null;
+// ── Parse one file ───────────────────────────────────────────────────
+function parseOverride(filePath, scope, scopeKey) {
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        const parsed = matter(raw);
+        const fm = (parsed.data ?? {});
+        const body = parsed.content.trim();
+        if (!body)
+            return null;
+        const defaultPriority = scope === 'global' ? 10 :
+            scope === 'agent' ? 50 :
+                100;
+        return {
+            body,
+            priority: typeof fm.priority === 'number' ? fm.priority : defaultPriority,
+            sourcePath: filePath,
+            scope,
+            scopeKey,
+        };
+    }
+    catch (err) {
+        logger.warn({ err, filePath }, 'Failed to parse prompt override — skipping');
+        return null;
+    }
+}
+function readMarkdownFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter(f => f.endsWith('.md'))
+        .map(f => path.join(dir, f));
+}
+// ── Loader ───────────────────────────────────────────────────────────
+export function loadPromptOverrides(opts) {
+    const baseDir = opts?.baseDir ?? BASE_DIR;
+    const root = rootDir(baseDir);
+    if (!existsSync(root)) {
+        mkdirSync(root, { recursive: true });
+    }
+    const out = [];
+    // _global.md (or any *.md) at root with bare name "_global"
+    const globalPath = path.join(root, '_global.md');
+    if (existsSync(globalPath)) {
+        const o = parseOverride(globalPath, 'global', null);
+        if (o)
+            out.push(o);
+    }
+    // agents/<slug>.md
+    for (const f of readMarkdownFiles(path.join(root, 'agents'))) {
+        const slug = path.basename(f, '.md');
+        const o = parseOverride(f, 'agent', slug);
+        if (o)
+            out.push(o);
+    }
+    // jobs/<jobName>.md
+    for (const f of readMarkdownFiles(path.join(root, 'jobs'))) {
+        const jobName = path.basename(f, '.md');
+        const o = parseOverride(f, 'job', jobName);
+        if (o)
+            out.push(o);
+    }
+    cached = out;
+    logger.info({ total: out.length, global: out.filter(o => o.scope === 'global').length, agent: out.filter(o => o.scope === 'agent').length, job: out.filter(o => o.scope === 'job').length }, 'Prompt overrides loaded');
+    return out;
+}
+export function getLoadedOverrides() {
+    return cached;
+}
+/**
+ * Resolve overrides applicable to a given job: global + agent (if agentSlug
+ * matches) + job (if jobName matches), sorted by priority ascending and
+ * concatenated into a single string. Empty if no overrides apply.
+ */
+export function loadPromptOverridesForJob(jobName, agentSlug, opts) {
+    // Use cached if loaded, else load fresh.
+    if (cached.length === 0) {
+        loadPromptOverrides(opts);
+    }
+    const applicable = cached.filter(o => {
+        if (o.scope === 'global')
+            return true;
+        if (o.scope === 'agent')
+            return agentSlug != null && o.scopeKey === agentSlug;
+        if (o.scope === 'job')
+            return o.scopeKey === jobName;
+        return false;
+    });
+    if (applicable.length === 0)
+        return '';
+    applicable.sort((a, b) => a.priority - b.priority);
+    return applicable.map(o => o.body).join('\n\n');
+}
+/** Install fs.watch on the overrides directory tree. Safe to call multiple times. */
+export function watchPromptOverrides(opts) {
+    if (watcherInstalled)
+        return;
+    const baseDir = opts?.baseDir ?? BASE_DIR;
+    const root = rootDir(baseDir);
+    if (!existsSync(root)) {
+        mkdirSync(root, { recursive: true });
+    }
+    // Pre-create subdirs so fs.watch picks up future changes
+    for (const sub of ['agents', 'jobs']) {
+        const p = path.join(root, sub);
+        if (!existsSync(p))
+            mkdirSync(p, { recursive: true });
+    }
+    try {
+        fsWatch(root, { recursive: true }, () => {
+            if (watchDebounce)
+                clearTimeout(watchDebounce);
+            watchDebounce = setTimeout(() => {
+                try {
+                    loadPromptOverrides(opts);
+                }
+                catch (err) {
+                    logger.warn({ err }, 'Hot reload failed — keeping previous overrides');
+                }
+            }, 250);
+        });
+        watcherInstalled = true;
+        logger.debug({ root }, 'Watching prompt-overrides for hot reload');
+    }
+    catch (err) {
+        logger.warn({ err }, 'Failed to install prompt-overrides watcher — hot reload disabled');
+    }
+}
+/** Test-only: clear cached state. */
+export function _resetLoaderState() {
+    cached = [];
+    watcherInstalled = false;
+    if (watchDebounce) {
+        clearTimeout(watchDebounce);
+        watchDebounce = null;
+    }
+}
+//# sourceMappingURL=loader.js.map

package/dist/agent/prompt-overrides/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Prompt Overrides — schema types.
+ *
+ * Markdown files in ~/.clementine/prompt-overrides/ that get prepended to
+ * cron job prompts at runtime. Frontmatter is optional; the bare body of
+ * a markdown file is enough to override a prompt.
+ *
+ * Layout:
+ *   _global.md                — appended for every job (low priority)
+ *   agents/<slug>.md          — every job for an agent
+ *   jobs/<jobName>.md         — specific job
+ *
+ * Default priority: global=10, agent=50, job=100. Lower priority concatenates first
+ * (i.e. "outermost" — read by the LLM earlier).
+ */
+export type OverridePosition = 'append' | 'prepend';
+export interface PromptOverrideFrontmatter {
+    schemaVersion?: 1;
+    priority?: number;
+    position?: OverridePosition;
+}
+export interface PromptOverride {
+    /** Raw body content (markdown), with frontmatter stripped. */
+    body: string;
+    /** Effective priority (frontmatter > scope default). */
+    priority: number;
+    /** Where the file lives — for logging only. */
+    sourcePath: string;
+    /** What scope this override targets. */
+    scope: 'global' | 'agent' | 'job';
+    /** For job/agent scope, the matched name; null for global. */
+    scopeKey: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agent/prompt-overrides/types.js

@@ -0,0 +1,17 @@
+/**
+ * Prompt Overrides — schema types.
+ *
+ * Markdown files in ~/.clementine/prompt-overrides/ that get prepended to
+ * cron job prompts at runtime. Frontmatter is optional; the bare body of
+ * a markdown file is enough to override a prompt.
+ *
+ * Layout:
+ *   _global.md                — appended for every job (low priority)
+ *   agents/<slug>.md          — every job for an agent
+ *   jobs/<jobName>.md         — specific job
+ *
+ * Default priority: global=10, agent=50, job=100. Lower priority concatenates first
+ * (i.e. "outermost" — read by the LLM earlier).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/gateway/cron-scheduler.js

@@ -17,6 +17,7 @@ import { listAllGoals, findGoalPath, readGoalById } from '../tools/shared.js';
 import { scanner } from '../security/scanner.js';
 import { parseAllWorkflows as parseAllWorkflowsSync } from '../agent/workflow-runner.js';
 import { SelfImproveLoop } from '../agent/self-improve.js';
+import { loadPromptOverridesForJob, watchPromptOverrides } from '../agent/prompt-overrides/loader.js';
 import { logAuditJsonl } from '../agent/hooks.js';
 import { listBackgroundTasks, markDone as markBgTaskDone, markFailed as markBgTaskFailed, markRunning as markBgTaskRunning, } from '../agent/background-tasks.js';
 import { outcomeStatusFromGoalDisposition, recentDecisions, recordDecisionOutcome, } from '../agent/proactive-ledger.js';
@@ -451,6 +452,7 @@ export class CronScheduler {
         this.watchCronFile();
         this.watchAgentsDir();
         this.watchWorkflowDir();
+        watchPromptOverrides();
         this.watchTriggers();
         // Deep-mode jobs are owned by the router (_deliverDeepResult). The
         // cron-scheduler callbacks below only dispatch for cron-originated runs;
@@ -888,6 +890,17 @@ export class CronScheduler {
                 ...advisorApplied,
             }, 'Execution advisor applied overrides');
         }
+        // User-authored prompt overrides — applied AFTER advisor enrichment so user
+        // intent sits at the top of the final prompt. These are static per-file,
+        // not subject to advisor suppression rules.
+        const userOverride = loadPromptOverridesForJob(job.name, job.agentSlug);
+        if (userOverride) {
+            // Mutable copy if not already cloned by the advisor block above.
+            if (!advisorApplied)
+                job = { ...job };
+            job.prompt = `${userOverride}\n\n${job.prompt}`;
+            logger.debug({ job: job.name, overrideLen: userOverride.length }, 'Applied user prompt overrides');
+        }
         // Compute effective timeout: advisor override > standard default
         const effectiveTimeoutMs = job.mode !== 'unleashed'
             ? (advice.adjustedTimeoutMs ?? CRON_STANDARD_TIMEOUT_MS)

package/dist/tools/admin-tools.js

@@ -1671,6 +1671,72 @@ export function registerAdminTools(server) {
             `Reason: ${reason}\n\n` +
             `The daemon will validate in a staging worktree, then commit + build + restart if compilation succeeds.`);
     });
+    // ── Prompt Overrides ────────────────────────────────────────────────────
+    server.tool('prompt_override_write', 'Write a markdown file under ~/.clementine/prompt-overrides/ that gets prepended to a job\'s prompt at runtime. Use this when you identify that a specific cron job, agent, or all jobs need additional guidance, context, or constraints. Survives `npm update -g clementine` and reloads in <1s. Scopes: "global" (every job), "agent" (every job for one agent), "job" (one specific job).', {
+        scope: z.enum(['global', 'agent', 'job']).describe('Which jobs the override applies to'),
+        scopeKey: z.string().optional().describe('For scope=agent: the agent slug. For scope=job: the job name. Ignored for scope=global.'),
+        content: z.string().min(1).describe('Markdown body to prepend to the prompt. May include optional gray-matter frontmatter for priority/position.'),
+        reason: z.string().describe('Why this override is being written — for the audit log.'),
+    }, async ({ scope, scopeKey, content, reason }) => {
+        if ((scope === 'agent' || scope === 'job') && !scopeKey) {
+            return textResult(`Error: scope="${scope}" requires scopeKey to be provided.`);
+        }
+        if (scopeKey && /[\/\\\.]/.test(scopeKey)) {
+            return textResult('Error: scopeKey cannot contain "/", "\\", or "."');
+        }
+        const ROOT = path.join(BASE_DIR, 'prompt-overrides');
+        let targetPath;
+        if (scope === 'global') {
+            targetPath = path.join(ROOT, '_global.md');
+        }
+        else if (scope === 'agent') {
+            targetPath = path.join(ROOT, 'agents', `${scopeKey}.md`);
+        }
+        else {
+            targetPath = path.join(ROOT, 'jobs', `${scopeKey}.md`);
+        }
+        try {
+            mkdirSync(path.dirname(targetPath), { recursive: true });
+            const tmp = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+            writeFileSync(tmp, content);
+            renameSync(tmp, targetPath);
+            logger.info({ scope, scopeKey, targetPath, reason, contentLen: content.length }, 'Wrote prompt override');
+            return textResult(`Prompt override written.\n` +
+                `Scope: ${scope}${scopeKey ? ` (${scopeKey})` : ''}\n` +
+                `Path: ${targetPath}\n` +
+                `Reason: ${reason}\n\n` +
+                `The override will be picked up on the next job run (hot-reloads via fs.watch within ~1s).`);
+        }
+        catch (err) {
+            logger.error({ err, scope, scopeKey, targetPath }, 'Failed to write prompt override');
+            return textResult(`Failed to write prompt override: ${String(err)}`);
+        }
+    });
+    server.tool('prompt_override_list', 'List all prompt overrides currently active in ~/.clementine/prompt-overrides/, grouped by scope. Use this to see what overrides exist before writing or removing one.', {}, async () => {
+        const ROOT = path.join(BASE_DIR, 'prompt-overrides');
+        if (!existsSync(ROOT)) {
+            return textResult('No prompt-overrides directory yet. Use prompt_override_write to create one.');
+        }
+        const lines = ['## Prompt Overrides'];
+        const globalPath = path.join(ROOT, '_global.md');
+        if (existsSync(globalPath))
+            lines.push(`- global: _global.md`);
+        const agentsDir = path.join(ROOT, 'agents');
+        if (existsSync(agentsDir)) {
+            for (const f of readdirSync(agentsDir).filter(f => f.endsWith('.md'))) {
+                lines.push(`- agent: ${path.basename(f, '.md')}`);
+            }
+        }
+        const jobsDir = path.join(ROOT, 'jobs');
+        if (existsSync(jobsDir)) {
+            for (const f of readdirSync(jobsDir).filter(f => f.endsWith('.md'))) {
+                lines.push(`- job: ${path.basename(f, '.md')}`);
+            }
+        }
+        if (lines.length === 1)
+            lines.push('(none)');
+        return textResult(lines.join('\n'));
+    });
     server.tool('update_self', 'Check for and apply upstream code updates. Can check without applying, or check and apply in one step.', {
         action: z.enum(['check', 'apply']).describe('"check" to see if updates are available, "apply" to pull and restart'),
     }, async ({ action }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.0.95",
+  "version": "1.0.96",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",