clementine-agent 1.0.96 → 1.0.97

package/dist/gateway/failure-diagnostics.d.ts

@@ -27,23 +27,40 @@ export type FixOperation = {
     op: 'remove';
     field: string;
 };
+/** CRON.md frontmatter edit (the original auto-apply shape). */
+export interface AutoApplyCron {
+    kind?: 'cron';
+    agentSlug?: string;
+    operations: FixOperation[];
+}
+/** Write a YAML rule to ~/.clementine/advisor-rules/user/<ruleId>.yaml */
+export interface AutoApplyAdvisorRule {
+    kind: 'advisor-rule';
+    ruleId: string;
+    yamlContent: string;
+}
+/** Write a markdown override to ~/.clementine/prompt-overrides/... */
+export interface AutoApplyPromptOverride {
+    kind: 'prompt-override';
+    scope: 'global' | 'agent' | 'job';
+    scopeKey?: string;
+    content: string;
+}
+export type AutoApply = AutoApplyCron | AutoApplyAdvisorRule | AutoApplyPromptOverride;
 export interface Diagnosis {
     rootCause: string;
     confidence: 'high' | 'medium' | 'low';
     proposedFix: {
-        type: 'config_change' | 'prompt_change' | 'agent_scope' | 'disable' | 'credential_refresh' | 'escalate_to_owner';
+        type: 'config_change' | 'prompt_change' | 'agent_scope' | 'disable' | 'credential_refresh' | 'advisor_rule' | 'prompt_override' | 'escalate_to_owner';
         details: string;
         diff?: string;
         /**
-         * When present, the fix can be applied with one click via the
-         * /api/cron/broken-jobs/:jobName/apply-fix endpoint. Operations are
-         * silently filtered against EDITABLE_FIELDS — a proposal that mixes
-         * safe and unsafe edits gets the unsafe ones dropped.
+         * When present, the fix can be applied with one click via the dashboard's
+         * apply-fix endpoint. Three shapes (kind=cron|advisor-rule|prompt-override).
+         * Each kind has its own validator that runs in sanitizeAutoApply before
+         * the proposal is cached, and again in fix-applier before any write.
          */
-        autoApply?: {
-            agentSlug?: string;
-            operations: FixOperation[];
-        };
+        autoApply?: AutoApply;
     };
     riskLevel: 'low' | 'medium' | 'high';
     generatedAt: string;

package/dist/gateway/failure-diagnostics.js

@@ -173,28 +173,43 @@ function buildPrompt(broken, jobDef, agentProfile, recentRuns) {
         '',
         '## Auto-apply contract',
         '',
-        'When (and ONLY when) the fix is a simple edit to one of these scalar fields — tier, mode, max_hours, max_turns, max_retries, enabled, agentSlug, work_dir, model, always_deliver, after, timeout_ms — also populate `proposedFix.autoApply`. The owner can one-click approve it from the dashboard.',
+        'When the fix is mechanical — set or remove a known scalar field, write a small advisor rule, or add prompt guidance — ALSO populate `proposedFix.autoApply`. The owner can one-click approve it. There are three KINDS of auto-apply, pick the one that matches:',
         '',
-        'For multi-line fields (prompt, pre_check, context, success_criteria), or for credential refreshes, or any change you are not very confident about: OMIT autoApply entirely. The owner will handle those manually.',
+        '### kind: "cron" (default — edit CRON.md frontmatter)',
+        'Use for: tier, mode, max_hours, max_turns, max_retries, enabled, agentSlug, work_dir, model, always_deliver, after, timeout_ms.',
+        'Shape: { "kind": "cron", "agentSlug"?: "...", "operations": [...] }',
+        'Operations: { "op": "set", "field": "<name>", "value": <scalar> } or { "op": "remove", "field": "<name>" }.',
+        'If the job is agent-scoped (job name has ":"), set agentSlug to the prefix.',
+        'Examples:',
+        '- Remove unleashed + companion + cap turns: { "kind": "cron", "operations": [{"op":"remove","field":"mode"}, {"op":"remove","field":"max_hours"}, {"op":"set","field":"max_turns","value":25}] }',
+        '- Bump maxTurns: { "kind": "cron", "operations": [{"op":"set","field":"max_turns","value":10}] }',
         '',
-        `If the job is agent-scoped (job name includes ":"), set autoApply.agentSlug to the part BEFORE the colon. Otherwise omit it (global CRON.md).`,
+        '### kind: "advisor-rule" (write a YAML rule to ~/.clementine/advisor-rules/user/)',
+        'Use when the fix is a behavioral rule that should affect ALL jobs matching some scope, not just one cron job. Examples: "for unleashed jobs, never bump maxTurns" or "for ross-the-sdr, always set timeout to 900s on max_turns errors".',
+        'Shape: { "kind": "advisor-rule", "ruleId": "kebab-case-id", "yamlContent": "<full yaml body>" }',
+        'The YAML body must be a valid advisor rule (schemaVersion: 1, id, description, priority, when, then). User rules at priority 100+ override builtins of the same id.',
+        'Example:',
+        '{ "kind": "advisor-rule", "ruleId": "ross-aggressive-timeout", "yamlContent": "schemaVersion: 1\\nid: ross-aggressive-timeout\\ndescription: Bump timeout for ross\\npriority: 105\\nappliesTo:\\n  agentSlug: ross-the-sdr\\nwhen:\\n  - kind: recentTimeoutHits\\n    window: 5\\n    atLeast: 1\\nthen:\\n  - kind: bumpTimeoutMs\\n    multiplier: 2.0" }',
         '',
-        'Operations use the shape { "op": "set", "field": "<name>", "value": <scalar> } or { "op": "remove", "field": "<name>" }. Values are strings, numbers, or booleans.',
+        '### kind: "prompt-override" (write a markdown file to ~/.clementine/prompt-overrides/)',
+        'Use when the fix is "give the LLM more guidance for this job/agent". Examples: a job consistently misses an edge case, an agent needs a reminder about output format.',
+        'Shape: { "kind": "prompt-override", "scope": "job"|"agent"|"global", "scopeKey": "<job or agent name>", "content": "<markdown body>" }',
+        'For scope=global, omit scopeKey. For scope=agent, scopeKey is the agent slug. For scope=job, scopeKey is the BARE job name (no agent prefix).',
+        'Example:',
+        '{ "kind": "prompt-override", "scope": "job", "scopeKey": "market-leader-followup", "content": "If the inbox query returns 0 rows, batch the duplicate-task cleanup in groups of 50 using bash heredoc loops. Do not enumerate task IDs in the prompt." }',
         '',
-        'Examples:',
-        '- Remove unleashed mode + its companion: operations: [{"op":"remove","field":"mode"}, {"op":"remove","field":"max_hours"}, {"op":"set","field":"max_turns","value":25}]',
-        '- Scope a broken global job to Ross\'s profile: operations: [{"op":"set","field":"agentSlug","value":"ross-the-sdr"}]',
-        '- Bump maxTurns on an under-resourced job: operations: [{"op":"set","field":"max_turns","value":10}]',
+        '## When NOT to use autoApply',
+        'For credential refreshes, multi-line CRON.md edits beyond the scalar allowlist, or any change you are not confident about: OMIT autoApply entirely. The owner will handle those manually.',
         '',
         '## Output schema (JSON only, no markdown fences):',
         '{',
-        '  "rootCause": "1-2 sentences explaining WHY the job is failing, referencing specific fields or error patterns from the CURRENT config",',
+        '  "rootCause": "1-2 sentences explaining WHY the job is failing",',
         '  "confidence": "high|medium|low",',
         '  "proposedFix": {',
-        '    "type": "config_change|prompt_change|agent_scope|disable|credential_refresh|escalate_to_owner",',
-        '    "details": "prose description of the fix, citing the exact field(s) to change",',
-        '    "diff": "optional: exact before/after diff",',
-        '    "autoApply": "optional: { agentSlug?, operations: [...] } — ONLY for simple scalar-field edits on the allowlist"',
+        '    "type": "config_change|prompt_change|agent_scope|disable|credential_refresh|advisor_rule|prompt_override|escalate_to_owner",',
+        '    "details": "prose description of the fix",',
+        '    "diff": "optional: before/after diff",',
+        '    "autoApply": "optional: one of the three shapes above"',
         '  },',
         '  "riskLevel": "low|medium|high"',
         '}',
@@ -230,32 +245,42 @@ function parseResponse(raw) {
     }
 }
 /**
- * Strictly validate and filter autoApply. Drops ops on non-allowlisted fields
- * silently (rather than rejecting the whole diagnosis). Returns null if
- * nothing valid remains.
+ * Strictly validate and filter autoApply. Dispatches on `kind` (default 'cron'
+ * for back-compat). Returns null if validation fails for the chosen kind.
  */
 function sanitizeAutoApply(raw) {
     if (!raw || typeof raw !== 'object')
         return null;
     const obj = raw;
+    const kind = typeof obj.kind === 'string' ? obj.kind : 'cron';
+    if (kind === 'cron')
+        return sanitizeAutoApplyCron(obj);
+    if (kind === 'advisor-rule')
+        return sanitizeAutoApplyAdvisorRule(obj);
+    if (kind === 'prompt-override')
+        return sanitizeAutoApplyPromptOverride(obj);
+    return null;
+}
+function sanitizeAutoApplyCron(raw) {
+    const obj = raw;
     if (!Array.isArray(obj.operations))
         return null;
     const operations = [];
     for (const op of obj.operations) {
         if (!op || typeof op !== 'object')
             continue;
-        const raw = op;
-        if (typeof raw.field !== 'string')
+        const r = op;
+        if (typeof r.field !== 'string')
             continue;
-        if (!EDITABLE_FIELDS.has(raw.field))
+        if (!EDITABLE_FIELDS.has(r.field))
             continue;
-        if (raw.op === 'remove') {
-            operations.push({ op: 'remove', field: raw.field });
+        if (r.op === 'remove') {
+            operations.push({ op: 'remove', field: r.field });
         }
-        else if (raw.op === 'set') {
-            const v = raw.value;
+        else if (r.op === 'set') {
+            const v = r.value;
             if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
-                operations.push({ op: 'set', field: raw.field, value: v });
+                operations.push({ op: 'set', field: r.field, value: v });
             }
         }
     }
@@ -264,7 +289,46 @@ function sanitizeAutoApply(raw) {
     const agentSlug = typeof obj.agentSlug === 'string' && /^[a-z0-9-]+$/i.test(obj.agentSlug)
         ? obj.agentSlug
         : undefined;
-    return agentSlug ? { agentSlug, operations } : { operations };
+    return { kind: 'cron', operations, ...(agentSlug ? { agentSlug } : {}) };
+}
+function sanitizeAutoApplyAdvisorRule(raw) {
+    const obj = raw;
+    if (typeof obj.ruleId !== 'string' || !obj.ruleId.trim())
+        return null;
+    if (!/^[a-z0-9-]+$/.test(obj.ruleId))
+        return null; // safe filename
+    if (typeof obj.yamlContent !== 'string' || !obj.yamlContent.trim())
+        return null;
+    if (obj.yamlContent.length > 10_000)
+        return null; // sanity bound
+    return {
+        kind: 'advisor-rule',
+        ruleId: obj.ruleId,
+        yamlContent: obj.yamlContent,
+    };
+}
+function sanitizeAutoApplyPromptOverride(raw) {
+    const obj = raw;
+    if (obj.scope !== 'global' && obj.scope !== 'agent' && obj.scope !== 'job')
+        return null;
+    if (typeof obj.content !== 'string' || !obj.content.trim())
+        return null;
+    if (obj.content.length > 20_000)
+        return null; // sanity bound
+    if (obj.scope === 'global') {
+        return { kind: 'prompt-override', scope: 'global', content: obj.content };
+    }
+    // agent or job — require scopeKey, validate as safe filename
+    if (typeof obj.scopeKey !== 'string' || !obj.scopeKey)
+        return null;
+    if (!/^[a-zA-Z0-9_:-]+$/.test(obj.scopeKey))
+        return null;
+    return {
+        kind: 'prompt-override',
+        scope: obj.scope,
+        scopeKey: obj.scopeKey,
+        content: obj.content,
+    };
 }
 /**
  * Diagnose one broken job. Returns a cached diagnosis if one exists and is

package/dist/gateway/failure-monitor.d.ts

@@ -25,28 +25,7 @@ export interface BrokenJob {
     circuitBreakerEngagedAt: string | null;
     lastAdvisorOpinion: string | null;
     /** Populated asynchronously by the diagnostic agent when available. */
-    diagnosis?: {
-        rootCause: string;
-        confidence: 'high' | 'medium' | 'low';
-        proposedFix: {
-            type: string;
-            details: string;
-            diff?: string;
-            autoApply?: {
-                agentSlug?: string;
-                operations: Array<{
-                    op: 'set';
-                    field: string;
-                    value: string | number | boolean;
-                } | {
-                    op: 'remove';
-                    field: string;
-                }>;
-            };
-        };
-        riskLevel: 'low' | 'medium' | 'high';
-        generatedAt: string;
-    };
+    diagnosis?: import('./failure-diagnostics.js').Diagnosis;
 }
 /**
  * Compute the current set of broken jobs by scanning all run logs.

package/dist/gateway/fix-applier.d.ts

@@ -11,7 +11,7 @@
  * Every apply writes a .bak next to the CRON.md and appends to an audit
  * log before touching the file.
  */
-import { type FixOperation } from './failure-diagnostics.js';
+import { type AutoApply, type FixOperation } from './failure-diagnostics.js';
 export interface ApplyResult {
     ok: boolean;
     message: string;
@@ -20,15 +20,19 @@ export interface ApplyResult {
     skippedOps?: FixOperation[];
     diff?: string;
 }
+export interface ApplyOptions {
+    dryRun?: boolean;
+    /** Override BASE_DIR for advisor-rule and prompt-override write paths. Tests only. */
+    baseDir?: string;
+}
 /**
- * Apply a proposed fix to the right CRON.md file. Idempotent with respect
- * to already-applied ops (remove on a missing field is a no-op, set on a
- * matching value is a no-op).
+ * Apply a proposed fix to the right target. Dispatches on autoApply.kind:
+ *   'cron'             — edit CRON.md frontmatter (the original path)
+ *   'advisor-rule'     — write a YAML rule under ~/.clementine/advisor-rules/user/
+ *   'prompt-override'  — write a markdown override under ~/.clementine/prompt-overrides/
+ *
+ * Each path has its own backup/audit. All idempotent: re-applying the same
+ * fix produces the same on-disk state.
  */
-export declare function applyFix(jobName: string, autoApply: {
-    agentSlug?: string;
-    operations: FixOperation[];
-}, opts?: {
-    dryRun?: boolean;
-}): ApplyResult;
+export declare function applyFix(jobName: string, autoApply: AutoApply, opts?: ApplyOptions): ApplyResult;
 //# sourceMappingURL=fix-applier.d.ts.map

package/dist/gateway/fix-applier.js

@@ -11,11 +11,12 @@
  * Every apply writes a .bak next to the CRON.md and appends to an audit
  * log before touching the file.
  */
-import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
 import pino from 'pino';
+import yaml from 'js-yaml';
 import { AGENTS_DIR, BASE_DIR, CRON_FILE } from '../config.js';
-import { EDITABLE_FIELDS } from './failure-diagnostics.js';
+import { EDITABLE_FIELDS, } from './failure-diagnostics.js';
 const logger = pino({ name: 'clementine.fix-applier' });
 const AUDIT_FILE = path.join(BASE_DIR, 'cron', 'fix-applier.log');
 /**
@@ -232,11 +233,26 @@ function findBlockEnd(lines, start) {
     return lines.length;
 }
 /**
- * Apply a proposed fix to the right CRON.md file. Idempotent with respect
- * to already-applied ops (remove on a missing field is a no-op, set on a
- * matching value is a no-op).
+ * Apply a proposed fix to the right target. Dispatches on autoApply.kind:
+ *   'cron'             — edit CRON.md frontmatter (the original path)
+ *   'advisor-rule'     — write a YAML rule under ~/.clementine/advisor-rules/user/
+ *   'prompt-override'  — write a markdown override under ~/.clementine/prompt-overrides/
+ *
+ * Each path has its own backup/audit. All idempotent: re-applying the same
+ * fix produces the same on-disk state.
  */
 export function applyFix(jobName, autoApply, opts = {}) {
+    // Default 'cron' for back-compat with old AutoApplyCron objects without kind.
+    const kind = autoApply.kind ?? 'cron';
+    if (kind === 'cron')
+        return applyCronFix(jobName, autoApply, opts);
+    if (kind === 'advisor-rule')
+        return applyAdvisorRuleFix(jobName, autoApply, opts);
+    if (kind === 'prompt-override')
+        return applyPromptOverrideFix(jobName, autoApply, opts);
+    return { ok: false, message: `Unknown autoApply.kind: ${String(kind)}` };
+}
+function applyCronFix(jobName, autoApply, opts) {
     const cronFile = resolveCronFile(jobName, autoApply);
     if (!cronFile) {
         return { ok: false, message: `No CRON.md found for ${jobName}` };
@@ -280,6 +296,7 @@ export function applyFix(jobName, autoApply, opts = {}) {
     const newContent = newLines.join('\n');
     writeFileSync(cronFile, newContent);
     appendAudit({
+        kind: 'cron',
         jobName,
         file: cronFile,
         applied,
@@ -296,6 +313,108 @@ export function applyFix(jobName, autoApply, opts = {}) {
         diff,
     };
 }
+// ── Advisor rule writer ──────────────────────────────────────────────
+function userRulesDir(baseDir) {
+    return path.join(baseDir, 'advisor-rules', 'user');
+}
+function applyAdvisorRuleFix(jobName, autoApply, opts) {
+    const targetDir = userRulesDir(opts.baseDir ?? BASE_DIR);
+    // Validate that the YAML parses and has the minimum schema shape. Don't
+    // require full Phase 2 zod validation here — the loader will reject invalid
+    // rules at read time and the next reload — but catch obvious malformed input.
+    let parsed;
+    try {
+        parsed = yaml.load(autoApply.yamlContent);
+    }
+    catch (err) {
+        return { ok: false, message: `Invalid YAML in advisor-rule body: ${String(err)}` };
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return { ok: false, message: 'advisor-rule yamlContent did not parse as a YAML object' };
+    }
+    const r = parsed;
+    if (r.schemaVersion !== 1) {
+        return { ok: false, message: 'advisor-rule must declare schemaVersion: 1' };
+    }
+    if (typeof r.id !== 'string' || r.id !== autoApply.ruleId) {
+        return { ok: false, message: `advisor-rule yamlContent id must match ruleId="${autoApply.ruleId}"` };
+    }
+    if (!Array.isArray(r.when) || !Array.isArray(r.then)) {
+        return { ok: false, message: 'advisor-rule must have when[] and then[] arrays' };
+    }
+    const targetPath = path.join(targetDir, `${autoApply.ruleId}.yaml`);
+    const diff = `+ advisor-rule ${autoApply.ruleId} → ${targetPath}`;
+    if (opts.dryRun) {
+        return { ok: true, message: 'Dry run: advisor-rule would be written', file: targetPath, diff };
+    }
+    try {
+        mkdirSync(targetDir, { recursive: true });
+        const tmp = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+        writeFileSync(tmp, autoApply.yamlContent);
+        renameSync(tmp, targetPath);
+    }
+    catch (err) {
+        return { ok: false, message: `Failed to write advisor rule: ${String(err)}` };
+    }
+    appendAudit({ kind: 'advisor-rule', jobName, file: targetPath, ruleId: autoApply.ruleId, diff });
+    logger.info({ jobName, ruleId: autoApply.ruleId, file: targetPath }, 'Applied advisor-rule fix');
+    return {
+        ok: true,
+        message: `Wrote advisor rule ${autoApply.ruleId} (hot-reloads on next eval)`,
+        file: targetPath,
+        diff,
+    };
+}
+// ── Prompt override writer ───────────────────────────────────────────
+function promptOverridesDir(baseDir) {
+    return path.join(baseDir, 'prompt-overrides');
+}
+function applyPromptOverrideFix(jobName, autoApply, opts) {
+    const root = promptOverridesDir(opts.baseDir ?? BASE_DIR);
+    // Resolve target path from scope.
+    let targetPath;
+    if (autoApply.scope === 'global') {
+        targetPath = path.join(root, '_global.md');
+    }
+    else {
+        if (!autoApply.scopeKey) {
+            return { ok: false, message: `prompt-override scope=${autoApply.scope} requires scopeKey` };
+        }
+        if (/[\/\\\.]/.test(autoApply.scopeKey)) {
+            return { ok: false, message: 'prompt-override scopeKey cannot contain "/", "\\", or "."' };
+        }
+        const sub = autoApply.scope === 'agent' ? 'agents' : 'jobs';
+        targetPath = path.join(root, sub, `${autoApply.scopeKey}.md`);
+    }
+    const diff = `+ prompt-override ${autoApply.scope}${autoApply.scopeKey ? `:${autoApply.scopeKey}` : ''} → ${targetPath}`;
+    if (opts.dryRun) {
+        return { ok: true, message: 'Dry run: prompt-override would be written', file: targetPath, diff };
+    }
+    try {
+        mkdirSync(path.dirname(targetPath), { recursive: true });
+        const tmp = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+        writeFileSync(tmp, autoApply.content);
+        renameSync(tmp, targetPath);
+    }
+    catch (err) {
+        return { ok: false, message: `Failed to write prompt override: ${String(err)}` };
+    }
+    appendAudit({
+        kind: 'prompt-override',
+        jobName,
+        file: targetPath,
+        scope: autoApply.scope,
+        scopeKey: autoApply.scopeKey,
+        diff,
+    });
+    logger.info({ jobName, scope: autoApply.scope, scopeKey: autoApply.scopeKey, file: targetPath }, 'Applied prompt-override fix');
+    return {
+        ok: true,
+        message: `Wrote prompt override ${autoApply.scope}${autoApply.scopeKey ? `:${autoApply.scopeKey}` : ''}`,
+        file: targetPath,
+        diff,
+    };
+}
 function appendAudit(entry) {
     try {
         mkdirSync(path.dirname(AUDIT_FILE), { recursive: true });

package/package.json

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