clementine-agent 1.0.87 → 1.0.89

package/README.md

@@ -585,6 +585,19 @@ The dashboard's "The Office" page shows each agent as an animated desk station w
 - Channel assignment, model badge, project badge, tool count
 - Edit and "Let Go" (delete) actions
 
+### Decision-loop reflection
+
+Each agent's autonomous decisions are recorded to a proactive ledger (action chosen, signal source, eventual outcome). The `decision_reflection` MCP tool reads that ledger, computes per-action success rates, and surfaces calibration patterns:
+
+- "act_now success rate is 33% — many autonomous actions did not advance"
+- "Queue-heavy bias: 12 queued vs 2 act_now — engine is being conservative"
+- "Zero ask_user despite active autonomous work"
+- Plus concrete tuning suggestions
+
+By default the report is saved to `vault/00-System/agents/<slug>/reflections/<date>.md`. Pass `append_to_memory: true` to also write a compact summary into the agent's `working-memory.md` so the next heartbeat tick reads it as prompt context — that's how agents self-tune without code changes.
+
+The shipped `vault/00-System/CRON.md` template includes a `weekly-decision-reflection` job (Sundays 9am) that runs reflection for the daemon and every active specialist.
+
 ### Per-agent heartbeats
 
 Each specialist (Ross / Sasha / your hires) gets their own autonomous heartbeat scheduler alongside Clementine's. The cycle:

package/dist/agent/decision-reflection.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Clementine TypeScript — Per-agent decision-loop reflection.
+ *
+ * Reads an agent's slice of the proactive decision ledger and produces
+ * a calibration report:
+ *
+ *   - How many decisions per action (act_now / queue / ask_user / snooze / ignore)
+ *   - Of those, how many had recorded outcomes
+ *   - Success rate (advanced / withOutcomes) per action
+ *   - Top signal sources by volume
+ *   - Plain-English patterns + concrete tuning suggestions
+ *
+ * The report is meant to land in the agent's working-memory so it
+ * shapes their next heartbeat tick — they read their own track record
+ * and self-correct without code changes.
+ *
+ * Pure analysis: no I/O side effects. The MCP tool wrapper handles
+ * file writes (history) and working-memory updates separately.
+ */
+import type { ProactiveAction, ProactiveDecision, ProactiveSource } from './proactive-engine.js';
+export interface ActionBucket {
+    decided: number;
+    withOutcomes: number;
+    advanced: number;
+    blocked: number;
+    failed: number;
+    /** advanced / withOutcomes * 100, or null if no outcomes recorded yet. */
+    successRatePct: number | null;
+}
+export interface DecisionReflection {
+    slug: string;
+    windowDays: number;
+    totalDecisions: number;
+    byAction: Record<ProactiveAction, ActionBucket>;
+    topSources: Array<{
+        source: ProactiveSource;
+        count: number;
+    }>;
+    patterns: string[];
+    suggestions: string[];
+    generatedAt: string;
+}
+/**
+ * Read the ledger, filter by agent + window, compute the calibration
+ * stats. Returns a DecisionReflection ready to format.
+ *
+ * Agent matching: a record belongs to `slug` when context.owner === slug
+ * OR context.goalId resolves to a goal whose owner is slug. For now we
+ * match only on context.owner — slug-by-goal is more expensive (would
+ * need listAllGoals) and not worth it until owner is consistently set.
+ */
+export declare function analyzeAgentDecisions(slug: string, windowDays?: number, opts?: {
+    ledgerPath?: string;
+    now?: Date;
+}): DecisionReflection;
+export declare function formatReflectionReport(r: DecisionReflection): string;
+/**
+ * Compact summary for working-memory append. Skips the full table and
+ * keeps just the patterns + suggestions so the agent's prompt doesn't
+ * get bloated with raw stats.
+ */
+export declare function formatReflectionSummary(r: DecisionReflection): string;
+/** Internal type alias used by tests / tool. */
+export type { ProactiveDecision };
+//# sourceMappingURL=decision-reflection.d.ts.map

package/dist/agent/decision-reflection.js

@@ -0,0 +1,240 @@
+/**
+ * Clementine TypeScript — Per-agent decision-loop reflection.
+ *
+ * Reads an agent's slice of the proactive decision ledger and produces
+ * a calibration report:
+ *
+ *   - How many decisions per action (act_now / queue / ask_user / snooze / ignore)
+ *   - Of those, how many had recorded outcomes
+ *   - Success rate (advanced / withOutcomes) per action
+ *   - Top signal sources by volume
+ *   - Plain-English patterns + concrete tuning suggestions
+ *
+ * The report is meant to land in the agent's working-memory so it
+ * shapes their next heartbeat tick — they read their own track record
+ * and self-correct without code changes.
+ *
+ * Pure analysis: no I/O side effects. The MCP tool wrapper handles
+ * file writes (history) and working-memory updates separately.
+ */
+import { recentDecisions } from './proactive-ledger.js';
+// ── Constants ────────────────────────────────────────────────────────
+const ALL_ACTIONS = ['act_now', 'queue', 'ask_user', 'snooze', 'ignore'];
+const LOW_SUCCESS_THRESHOLD = 50; // < 50% success → flag as miscalibrated
+const HIGH_VOLUME_THRESHOLD = 20; // > 20 decisions in window → "active loop"
+const DORMANT_THRESHOLD = 0; // 0 decisions → "dormant"
+function emptyBucket() {
+    return { decided: 0, withOutcomes: 0, advanced: 0, blocked: 0, failed: 0, successRatePct: null };
+}
+function emptyByAction() {
+    const out = {};
+    for (const a of ALL_ACTIONS)
+        out[a] = emptyBucket();
+    return out;
+}
+// ── Analysis ─────────────────────────────────────────────────────────
+/**
+ * Read the ledger, filter by agent + window, compute the calibration
+ * stats. Returns a DecisionReflection ready to format.
+ *
+ * Agent matching: a record belongs to `slug` when context.owner === slug
+ * OR context.goalId resolves to a goal whose owner is slug. For now we
+ * match only on context.owner — slug-by-goal is more expensive (would
+ * need listAllGoals) and not worth it until owner is consistently set.
+ */
+export function analyzeAgentDecisions(slug, windowDays = 7, opts) {
+    const now = opts?.now ?? new Date();
+    const sinceMs = windowDays * 24 * 60 * 60 * 1000;
+    const records = recentDecisions({ sinceMs }, opts?.ledgerPath ? { filePath: opts.ledgerPath, now } : { now });
+    // Filter to records relevant to this agent. Inclusion rule:
+    //   - context.owner === slug (preferred — explicitly attributed)
+    //   - else if slug === 'clementine': include records with no owner
+    //     (the daemon's own decisions default to no-owner)
+    const isClementine = slug === 'clementine';
+    const mine = records.filter((r) => {
+        const owner = r.context.owner;
+        if (owner)
+            return owner === slug;
+        return isClementine; // unowned → Clementine
+    });
+    // Outcome records share the original decision's id and have an
+    // `outcome` field. Index by id so we can pair decisions with their
+    // outcomes in one pass.
+    const outcomeById = new Map();
+    for (const r of mine) {
+        if (r.outcome)
+            outcomeById.set(r.id, r.outcome.status);
+    }
+    const byAction = emptyByAction();
+    const sourceCounts = new Map();
+    let totalDecisions = 0;
+    for (const r of mine) {
+        if (r.outcome)
+            continue; // outcomes are indexed; only count original decisions here
+        totalDecisions++;
+        const action = r.decision.action;
+        const bucket = byAction[action];
+        bucket.decided++;
+        const outcomeStatus = outcomeById.get(r.id);
+        if (outcomeStatus !== undefined) {
+            bucket.withOutcomes++;
+            if (outcomeStatus === 'advanced')
+                bucket.advanced++;
+            else if (typeof outcomeStatus === 'string' && outcomeStatus.startsWith('blocked-'))
+                bucket.blocked++;
+            else if (outcomeStatus === 'failed')
+                bucket.failed++;
+        }
+        const src = r.decision.source;
+        sourceCounts.set(src, (sourceCounts.get(src) ?? 0) + 1);
+    }
+    // Compute success rates
+    for (const a of ALL_ACTIONS) {
+        const b = byAction[a];
+        b.successRatePct = b.withOutcomes > 0 ? Math.round((b.advanced / b.withOutcomes) * 100) : null;
+    }
+    const topSources = [...sourceCounts.entries()]
+        .map(([source, count]) => ({ source, count }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 5);
+    const { patterns, suggestions } = derivePatterns({ slug, totalDecisions, byAction, topSources, windowDays });
+    return {
+        slug,
+        windowDays,
+        totalDecisions,
+        byAction,
+        topSources,
+        patterns,
+        suggestions,
+        generatedAt: now.toISOString(),
+    };
+}
+/**
+ * Derive plain-English patterns + tuning suggestions from the stats.
+ * Each pattern is a one-line observation; each suggestion is concrete
+ * advice the agent (or human) can act on.
+ */
+function derivePatterns(input) {
+    const patterns = [];
+    const suggestions = [];
+    if (input.totalDecisions === DORMANT_THRESHOLD) {
+        patterns.push(`No decisions recorded in the last ${input.windowDays} days.`);
+        suggestions.push('Agent is dormant. Either no signals are reaching the heartbeat, or every signal is being deduped. Check the proactive ledger directly to confirm.');
+        return { patterns, suggestions };
+    }
+    if (input.totalDecisions >= HIGH_VOLUME_THRESHOLD) {
+        patterns.push(`High decision volume: ${input.totalDecisions} decisions in ${input.windowDays} days.`);
+    }
+    const actNow = input.byAction.act_now;
+    if (actNow.withOutcomes >= 3 && (actNow.successRatePct ?? 100) < LOW_SUCCESS_THRESHOLD) {
+        patterns.push(`act_now success rate is ${actNow.successRatePct}% (${actNow.advanced}/${actNow.withOutcomes}). Low — many autonomous actions did not advance.`);
+        suggestions.push('Raise the urgency threshold for act_now (in proactive-engine.ts decideGoalAdvancement / decideDailyPlanPriority) — currently firing too aggressively. Consider requiring urgency >= 5 instead of >= 4.');
+    }
+    const queue = input.byAction.queue;
+    if (queue.withOutcomes >= 3 && (queue.successRatePct ?? 100) < LOW_SUCCESS_THRESHOLD) {
+        patterns.push(`Queued items are not landing: ${queue.advanced}/${queue.withOutcomes} advanced (${queue.successRatePct}%).`);
+        suggestions.push('Queued work is going stale. Review the work-queue dwell time — items may be timing out before the heartbeat runs them.');
+    }
+    if (queue.decided > actNow.decided * 3 && actNow.decided > 0) {
+        patterns.push(`Queue-heavy bias: ${queue.decided} queued vs ${actNow.decided} act_now. The engine is being conservative.`);
+        suggestions.push('If most queued items eventually advance manually, consider lowering the queue→act_now threshold or expanding act_now eligibility.');
+    }
+    const blockedTotal = ALL_ACTIONS.reduce((sum, a) => sum + input.byAction[a].blocked, 0);
+    if (blockedTotal >= 3) {
+        patterns.push(`${blockedTotal} decisions ended blocked (waiting on user/external).`);
+        suggestions.push('Frequent blocking suggests the agent is hitting questions only the owner can answer. Review whether earlier ask_user prompts would clear the blockage faster.');
+    }
+    const askUserCount = input.byAction.ask_user.decided;
+    if (askUserCount === 0 && actNow.decided + queue.decided >= 5) {
+        patterns.push('Zero ask_user decisions despite active autonomous work.');
+        suggestions.push('Agent never asked for owner input over the window. Either everything is unambiguously autonomous (good) or the agent is over-deciding without clarity (suspect when blocked outcomes are non-trivial).');
+    }
+    const failedTotal = ALL_ACTIONS.reduce((sum, a) => sum + input.byAction[a].failed, 0);
+    if (failedTotal >= 3) {
+        patterns.push(`${failedTotal} decisions ended in failed outcomes.`);
+        suggestions.push('Multiple failures — check cron logs for the failing job names. May indicate a tool that needs maintenance, a budget cap being hit, or a misconfigured trigger.');
+    }
+    if (patterns.length === 0) {
+        patterns.push('No notable patterns detected — calibration looks healthy for this window.');
+    }
+    return { patterns, suggestions };
+}
+// ── Markdown formatter ───────────────────────────────────────────────
+const ACTION_LABELS = {
+    act_now: 'Doing now',
+    queue: 'Queued',
+    ask_user: 'Needs you',
+    snooze: 'Snoozed',
+    ignore: 'Skipped',
+};
+export function formatReflectionReport(r) {
+    const lines = [];
+    lines.push(`# Decision reflection — ${r.slug}`);
+    lines.push('');
+    lines.push(`Generated: ${r.generatedAt}  `);
+    lines.push(`Window: last ${r.windowDays} day(s)  `);
+    lines.push(`Total decisions: **${r.totalDecisions}**`);
+    lines.push('');
+    if (r.totalDecisions === 0) {
+        lines.push('## No decisions in window');
+        lines.push('');
+        for (const p of r.patterns)
+            lines.push(`- ${p}`);
+        if (r.suggestions.length > 0) {
+            lines.push('');
+            lines.push('### Suggestions');
+            for (const s of r.suggestions)
+                lines.push(`- ${s}`);
+        }
+        return lines.join('\n');
+    }
+    lines.push('## By action');
+    lines.push('');
+    lines.push('| Action | Decided | Outcomes | Advanced | Blocked | Failed | Success |');
+    lines.push('|---|---:|---:|---:|---:|---:|---:|');
+    for (const a of ALL_ACTIONS) {
+        const b = r.byAction[a];
+        if (b.decided === 0)
+            continue;
+        const pct = b.successRatePct === null ? '—' : `${b.successRatePct}%`;
+        lines.push(`| ${ACTION_LABELS[a]} (${a}) | ${b.decided} | ${b.withOutcomes} | ${b.advanced} | ${b.blocked} | ${b.failed} | ${pct} |`);
+    }
+    if (r.topSources.length > 0) {
+        lines.push('');
+        lines.push('## Top sources');
+        for (const s of r.topSources) {
+            lines.push(`- **${s.source}**: ${s.count}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Patterns');
+    for (const p of r.patterns)
+        lines.push(`- ${p}`);
+    if (r.suggestions.length > 0) {
+        lines.push('');
+        lines.push('## Suggestions');
+        for (const s of r.suggestions)
+            lines.push(`- ${s}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Compact summary for working-memory append. Skips the full table and
+ * keeps just the patterns + suggestions so the agent's prompt doesn't
+ * get bloated with raw stats.
+ */
+export function formatReflectionSummary(r) {
+    const lines = [];
+    lines.push(`### Self-reflection (${r.generatedAt.slice(0, 10)}, last ${r.windowDays}d, ${r.totalDecisions} decisions)`);
+    lines.push('');
+    for (const p of r.patterns)
+        lines.push(`- ${p}`);
+    if (r.suggestions.length > 0) {
+        lines.push('');
+        lines.push('**Tuning suggestions:**');
+        for (const s of r.suggestions)
+            lines.push(`- ${s}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=decision-reflection.js.map

package/dist/agent/webhook-actions.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Clementine TypeScript — Webhook → action dispatch.
+ *
+ * External services (Salesforce, GitHub, calendar, email) POST events
+ * to /webhook-action/:source. This module turns those events into
+ * agentic actions:
+ *
+ *   - `wake_agent`            → write wake sentinel; agent ticks within ~3s
+ *   - `start_background_task` → create a pending task; cron-scheduler picks
+ *                                it up and runs unleashed
+ *
+ * Configuration: ~/.clementine/webhook-actions.json
+ *
+ *   {
+ *     "hooks": [
+ *       {
+ *         "source": "github",
+ *         "secretEnv": "GITHUB_WEBHOOK_SECRET",
+ *         "on": [
+ *           {
+ *             "match": { "action": "opened", "pull_request": "*" },
+ *             "do": "wake_agent",
+ *             "agent": "ross-the-sdr",
+ *             "reason": "PR opened — review needed"
+ *           }
+ *         ]
+ *       }
+ *     ]
+ *   }
+ *
+ * Match values: literal strings/numbers/booleans for exact match, or "*"
+ * to require the field be present (any value, non-null/undefined). Dot
+ * notation supported for nested fields ("payload.user.id"). All conditions
+ * in a `match` block must hold (AND).
+ *
+ * Templating: `prompt` and `reason` strings can interpolate payload
+ * fields with `{{ field.path }}`. Missing fields render as empty string.
+ *
+ * Every dispatched event is logged to ~/.clementine/webhook-actions/log.jsonl
+ * (rotated at 1MB / 1000 lines, 30-day retention).
+ */
+export type WebhookActionVerb = 'wake_agent' | 'start_background_task';
+export interface WebhookActionRule {
+    /** Field/value conditions, all must match. Use "*" for "field present". */
+    match?: Record<string, string | number | boolean>;
+    do: WebhookActionVerb;
+    agent: string;
+    /** For wake_agent — short reason annotated on the wake sentinel. */
+    reason?: string;
+    /** For start_background_task — the prompt template. Supports {{ field.path }}. */
+    prompt?: string;
+    /** For start_background_task — wall-clock cap. Default 30. */
+    maxMinutes?: number;
+}
+export interface WebhookActionSource {
+    source: string;
+    /** Env var holding the HMAC secret. Required unless `secret` is set inline. */
+    secretEnv?: string;
+    /** Inline secret (for tests / local-only setups). Prefer secretEnv in prod. */
+    secret?: string;
+    on: WebhookActionRule[];
+}
+export interface WebhookActionConfig {
+    hooks: WebhookActionSource[];
+}
+export interface DispatchResult {
+    matched: number;
+    dispatched: number;
+    errors: string[];
+    log: Array<{
+        rule: WebhookActionRule;
+        ok: boolean;
+        message: string;
+    }>;
+}
+export declare function loadWebhookActionConfig(opts?: {
+    configPath?: string;
+}): WebhookActionConfig;
+export declare function getSourceConfig(source: string, opts?: {
+    configPath?: string;
+}): WebhookActionSource | null;
+/** All match conditions hold. "*" means "field is present (non-null/undefined)". */
+export declare function ruleMatches(rule: WebhookActionRule, payload: unknown): boolean;
+/** Replace {{ dot.path }} in a template with payload values. Missing → "". */
+export declare function renderTemplate(template: string, payload: unknown): string;
+/**
+ * Match the payload against every rule in the source config and dispatch
+ * all matches. Each rule is independent — multiple matches all fire.
+ */
+export declare function dispatchWebhookActions(source: string, payload: unknown, opts?: {
+    configPath?: string;
+    baseDir?: string;
+}): DispatchResult;
+export interface WebhookEventLogEntry {
+    timestamp: string;
+    source: string;
+    verified: boolean;
+    matched: number;
+    dispatched: number;
+    errors: string[];
+    payloadPreview: string;
+}
+export declare function logWebhookEvent(entry: WebhookEventLogEntry, opts?: {
+    logPath?: string;
+    logDir?: string;
+}): void;
+export declare function recentWebhookEvents(limit?: number, opts?: {
+    logPath?: string;
+}): WebhookEventLogEntry[];
+export declare const _internals: {
+    CONFIG_PATH: string;
+    LOG_PATH: string;
+    LOG_DIR: string;
+    WAKE_DIR: string;
+};
+//# sourceMappingURL=webhook-actions.d.ts.map

package/dist/agent/webhook-actions.js

@@ -0,0 +1,240 @@
+/**
+ * Clementine TypeScript — Webhook → action dispatch.
+ *
+ * External services (Salesforce, GitHub, calendar, email) POST events
+ * to /webhook-action/:source. This module turns those events into
+ * agentic actions:
+ *
+ *   - `wake_agent`            → write wake sentinel; agent ticks within ~3s
+ *   - `start_background_task` → create a pending task; cron-scheduler picks
+ *                                it up and runs unleashed
+ *
+ * Configuration: ~/.clementine/webhook-actions.json
+ *
+ *   {
+ *     "hooks": [
+ *       {
+ *         "source": "github",
+ *         "secretEnv": "GITHUB_WEBHOOK_SECRET",
+ *         "on": [
+ *           {
+ *             "match": { "action": "opened", "pull_request": "*" },
+ *             "do": "wake_agent",
+ *             "agent": "ross-the-sdr",
+ *             "reason": "PR opened — review needed"
+ *           }
+ *         ]
+ *       }
+ *     ]
+ *   }
+ *
+ * Match values: literal strings/numbers/booleans for exact match, or "*"
+ * to require the field be present (any value, non-null/undefined). Dot
+ * notation supported for nested fields ("payload.user.id"). All conditions
+ * in a `match` block must hold (AND).
+ *
+ * Templating: `prompt` and `reason` strings can interpolate payload
+ * fields with `{{ field.path }}`. Missing fields render as empty string.
+ *
+ * Every dispatched event is logged to ~/.clementine/webhook-actions/log.jsonl
+ * (rotated at 1MB / 1000 lines, 30-day retention).
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+import { BASE_DIR } from '../config.js';
+import { createBackgroundTask } from './background-tasks.js';
+// ── Storage paths ────────────────────────────────────────────────────
+const CONFIG_PATH = path.join(BASE_DIR, 'webhook-actions.json');
+const LOG_DIR = path.join(BASE_DIR, 'webhook-actions');
+const LOG_PATH = path.join(LOG_DIR, 'log.jsonl');
+const WAKE_DIR = path.join(BASE_DIR, 'heartbeat', 'wake');
+const LOG_MAX_BYTES = 1_000_000;
+const LOG_MAX_LINES = 1000;
+const LOG_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+// ── Config I/O ───────────────────────────────────────────────────────
+export function loadWebhookActionConfig(opts) {
+    const file = opts?.configPath ?? CONFIG_PATH;
+    if (!existsSync(file))
+        return { hooks: [] };
+    try {
+        const raw = JSON.parse(readFileSync(file, 'utf-8'));
+        if (!Array.isArray(raw.hooks))
+            return { hooks: [] };
+        return { hooks: raw.hooks };
+    }
+    catch {
+        return { hooks: [] };
+    }
+}
+export function getSourceConfig(source, opts) {
+    return loadWebhookActionConfig(opts).hooks.find((h) => h.source === source) ?? null;
+}
+// ── Matcher ──────────────────────────────────────────────────────────
+/** Read a dot-path from a JSON-ish object. Returns undefined if any segment is missing. */
+function readPath(obj, dotPath) {
+    if (obj == null || typeof obj !== 'object')
+        return undefined;
+    let cursor = obj;
+    for (const segment of dotPath.split('.')) {
+        if (cursor == null || typeof cursor !== 'object')
+            return undefined;
+        cursor = cursor[segment];
+    }
+    return cursor;
+}
+/** All match conditions hold. "*" means "field is present (non-null/undefined)". */
+export function ruleMatches(rule, payload) {
+    const conds = rule.match;
+    if (!conds || Object.keys(conds).length === 0)
+        return true; // empty match = match-all
+    for (const [pathSpec, expected] of Object.entries(conds)) {
+        const actual = readPath(payload, pathSpec);
+        if (expected === '*') {
+            if (actual === undefined || actual === null)
+                return false;
+            continue;
+        }
+        // Loose equality: 1 == "1", true == "true". Real users put strings in JSON; loose is friendlier.
+        // eslint-disable-next-line eqeqeq
+        if (actual == expected)
+            continue;
+        return false;
+    }
+    return true;
+}
+/** Replace {{ dot.path }} in a template with payload values. Missing → "". */
+export function renderTemplate(template, payload) {
+    return template.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, dotPath) => {
+        const v = readPath(payload, dotPath);
+        if (v == null)
+            return '';
+        if (typeof v === 'object')
+            return JSON.stringify(v);
+        return String(v);
+    });
+}
+function wakeSentinelPath(slug, baseDir) {
+    return path.join(baseDir, 'heartbeat', 'wake', `${slug}.json`);
+}
+function dispatchOne(rule, source, payload, env) {
+    const baseDir = env.baseDir ?? BASE_DIR;
+    if (rule.do === 'wake_agent') {
+        try {
+            const wakeDir = path.join(baseDir, 'heartbeat', 'wake');
+            mkdirSync(wakeDir, { recursive: true });
+            const reason = rule.reason ? renderTemplate(rule.reason, payload) : `webhook:${source}`;
+            const sentinel = {
+                targetSlug: rule.agent,
+                fromSlug: `webhook:${source}`,
+                reason: reason.slice(0, 200),
+                requestedAt: new Date().toISOString(),
+            };
+            writeFileSync(wakeSentinelPath(rule.agent, baseDir), JSON.stringify(sentinel, null, 2));
+            return { ok: true, message: `Woke ${rule.agent} (${reason})` };
+        }
+        catch (err) {
+            return { ok: false, message: `wake_agent failed: ${String(err).slice(0, 200)}` };
+        }
+    }
+    if (rule.do === 'start_background_task') {
+        if (!rule.prompt) {
+            return { ok: false, message: 'start_background_task: rule has no `prompt` template' };
+        }
+        try {
+            const prompt = renderTemplate(rule.prompt, payload);
+            const task = createBackgroundTask({
+                fromAgent: rule.agent,
+                prompt,
+                maxMinutes: rule.maxMinutes ?? 30,
+            }, env.baseDir ? { dir: path.join(env.baseDir, 'background-tasks') } : undefined);
+            return { ok: true, message: `Queued background task ${task.id} for ${rule.agent}` };
+        }
+        catch (err) {
+            return { ok: false, message: `start_background_task failed: ${String(err).slice(0, 200)}` };
+        }
+    }
+    // Exhaustiveness check — should never hit at runtime if types are honored.
+    return { ok: false, message: `Unknown action verb: ${rule.do}` };
+}
+/**
+ * Match the payload against every rule in the source config and dispatch
+ * all matches. Each rule is independent — multiple matches all fire.
+ */
+export function dispatchWebhookActions(source, payload, opts) {
+    const cfg = getSourceConfig(source, opts);
+    const result = { matched: 0, dispatched: 0, errors: [], log: [] };
+    if (!cfg) {
+        result.errors.push(`No webhook-action config for source "${source}"`);
+        return result;
+    }
+    for (const rule of cfg.on) {
+        if (!ruleMatches(rule, payload))
+            continue;
+        result.matched++;
+        const r = dispatchOne(rule, source, payload, { baseDir: opts?.baseDir });
+        result.log.push({ rule, ok: r.ok, message: r.message });
+        if (r.ok)
+            result.dispatched++;
+        else
+            result.errors.push(r.message);
+    }
+    return result;
+}
+function rotateLogIfNeeded(opts) {
+    const file = opts?.logPath ?? LOG_PATH;
+    try {
+        if (!existsSync(file))
+            return;
+        const { size } = statSync(file);
+        if (size <= LOG_MAX_BYTES)
+            return;
+        const lines = readFileSync(file, 'utf-8').trim().split('\n').filter(Boolean);
+        if (lines.length <= LOG_MAX_LINES)
+            return;
+        const cutoff = Date.now() - LOG_MAX_AGE_MS;
+        const kept = [];
+        for (const line of lines.slice(-LOG_MAX_LINES)) {
+            try {
+                const e = JSON.parse(line);
+                const ts = new Date(e.timestamp).getTime();
+                if (Number.isFinite(ts) && ts >= cutoff)
+                    kept.push(line);
+            }
+            catch { /* drop malformed */ }
+        }
+        writeFileSync(file, kept.join('\n') + (kept.length ? '\n' : ''));
+    }
+    catch { /* non-fatal */ }
+}
+export function logWebhookEvent(entry, opts) {
+    try {
+        const dir = opts?.logDir ?? LOG_DIR;
+        const file = opts?.logPath ?? LOG_PATH;
+        mkdirSync(dir, { recursive: true });
+        appendFileSync(file, JSON.stringify(entry) + '\n');
+        setImmediate(() => rotateLogIfNeeded(opts));
+    }
+    catch { /* non-fatal */ }
+}
+export function recentWebhookEvents(limit = 50, opts) {
+    try {
+        const file = opts?.logPath ?? LOG_PATH;
+        if (!existsSync(file))
+            return [];
+        const lines = readFileSync(file, 'utf-8').trim().split('\n').filter(Boolean);
+        const out = [];
+        for (const line of lines.slice(-limit).reverse()) {
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch { /* skip */ }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+// ── Test-only ────────────────────────────────────────────────────────
+export const _internals = { CONFIG_PATH, LOG_PATH, LOG_DIR, WAKE_DIR };
+//# sourceMappingURL=webhook-actions.js.map

package/dist/cli/dashboard.js

@@ -1364,6 +1364,66 @@ export async function cmdDashboard(opts) {
             diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
         return diff === 0;
     }
+    // ── Webhook → action triggers ─────────────────────────────────────
+    // Sibling of /webhook/:slug. Where /webhook/:slug ingests data into
+    // the brain, /webhook-action/:source dispatches agentic actions
+    // (wake an agent, start a background task) based on a YAML-ish config
+    // at ~/.clementine/webhook-actions.json. Same HMAC verification.
+    app.post('/webhook-action/:source', rawBodyParser, async (req, res) => {
+        const sourceParam = req.params.source;
+        const { getSourceConfig, dispatchWebhookActions, logWebhookEvent, } = await import('../agent/webhook-actions.js');
+        const cfg = getSourceConfig(sourceParam);
+        if (!cfg) {
+            res.status(404).json({ error: `No webhook-action config for source "${sourceParam}"` });
+            return;
+        }
+        // Resolve the HMAC secret (env first, inline fallback for local dev).
+        const secret = (cfg.secretEnv ? process.env[cfg.secretEnv] : undefined) ?? cfg.secret ?? '';
+        if (!secret) {
+            res.status(500).json({ error: `Webhook source "${sourceParam}" has no secret configured` });
+            return;
+        }
+        const sig = String(req.headers['x-signature'] ?? req.headers['x-hub-signature-256'] ?? '').trim();
+        const rawBody = Buffer.isBuffer(req.body) ? req.body : Buffer.from(String(req.body ?? ''));
+        const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
+        const given = sig.startsWith('sha256=') ? sig.slice('sha256='.length) : sig;
+        if (!given || !safeHexEquals(given, expected)) {
+            logWebhookEvent({
+                timestamp: new Date().toISOString(),
+                source: sourceParam,
+                verified: false,
+                matched: 0,
+                dispatched: 0,
+                errors: ['HMAC signature mismatch'],
+                payloadPreview: rawBody.toString('utf-8').slice(0, 200),
+            });
+            res.status(401).json({ error: 'Invalid or missing HMAC signature' });
+            return;
+        }
+        let payload;
+        try {
+            payload = JSON.parse(rawBody.toString('utf-8'));
+        }
+        catch (err) {
+            res.status(400).json({ error: `Body is not JSON: ${err instanceof Error ? err.message : String(err)}` });
+            return;
+        }
+        const result = dispatchWebhookActions(sourceParam, payload);
+        logWebhookEvent({
+            timestamp: new Date().toISOString(),
+            source: sourceParam,
+            verified: true,
+            matched: result.matched,
+            dispatched: result.dispatched,
+            errors: result.errors,
+            payloadPreview: rawBody.toString('utf-8').slice(0, 200),
+        });
+        res.json({
+            matched: result.matched,
+            dispatched: result.dispatched,
+            errors: result.errors,
+        });
+    });
     // Only parse JSON bodies on POST/PUT/PATCH — GET requests don't need body parsing.
     // Registered AFTER the webhook route so /webhook/* keeps its raw body.
     app.use((req, res, next) => {
@@ -1978,6 +2038,36 @@ export async function cmdDashboard(opts) {
     app.get('/api/agent-heartbeats', (_req, res) => {
         res.json(getAgentHeartbeats());
     });
+    app.get('/api/webhook-actions', async (_req, res) => {
+        try {
+            const { loadWebhookActionConfig, recentWebhookEvents } = await import('../agent/webhook-actions.js');
+            const cfg = loadWebhookActionConfig();
+            // Don't leak secrets — strip secret/secretEnv from the config response
+            const sanitized = {
+                hooks: cfg.hooks.map((h) => ({
+                    source: h.source,
+                    hasSecret: Boolean(h.secret) || Boolean(h.secretEnv),
+                    secretEnv: h.secretEnv ?? null,
+                    rules: h.on.length,
+                    on: h.on.map((r) => ({
+                        do: r.do,
+                        agent: r.agent,
+                        match: r.match ?? {},
+                        reason: r.reason,
+                        promptHead: r.prompt ? r.prompt.slice(0, 120) : undefined,
+                        maxMinutes: r.maxMinutes,
+                    })),
+                })),
+            };
+            res.json({
+                config: sanitized,
+                recent: recentWebhookEvents(50),
+            });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err).slice(0, 200) });
+        }
+    });
     app.get('/api/background-tasks', async (_req, res) => {
         try {
             const { listBackgroundTasks } = await import('../agent/background-tasks.js');

package/dist/tools/decision-reflection-tools.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Clementine TypeScript — Decision-loop reflection MCP tool.
+ *
+ * `decision_reflection` runs the analysis from agent/decision-reflection.ts
+ * for an agent and surfaces the result as a markdown report. Optionally
+ * persists the report to the agent's reflections history and/or appends
+ * a summary to their working-memory so the next heartbeat tick reads it
+ * as prompt context.
+ *
+ * Intended usage:
+ *   - Manual call by the owner ("Clementine, reflect on your week")
+ *   - Weekly cron job that calls this for each active agent
+ *   - On-demand by an agent when they suspect they're miscalibrated
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDecisionReflectionTools(server: McpServer): void;
+//# sourceMappingURL=decision-reflection-tools.d.ts.map

package/dist/tools/decision-reflection-tools.js

@@ -0,0 +1,83 @@
+/**
+ * Clementine TypeScript — Decision-loop reflection MCP tool.
+ *
+ * `decision_reflection` runs the analysis from agent/decision-reflection.ts
+ * for an agent and surfaces the result as a markdown report. Optionally
+ * persists the report to the agent's reflections history and/or appends
+ * a summary to their working-memory so the next heartbeat tick reads it
+ * as prompt context.
+ *
+ * Intended usage:
+ *   - Manual call by the owner ("Clementine, reflect on your week")
+ *   - Weekly cron job that calls this for each active agent
+ *   - On-demand by an agent when they suspect they're miscalibrated
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { analyzeAgentDecisions, formatReflectionReport, formatReflectionSummary, } from '../agent/decision-reflection.js';
+import { ACTIVE_AGENT_SLUG, AGENTS_DIR, logger, textResult } from './shared.js';
+function reflectionsDir(slug) {
+    return path.join(AGENTS_DIR, slug, 'reflections');
+}
+function workingMemoryPath(slug) {
+    return path.join(AGENTS_DIR, slug, 'working-memory.md');
+}
+function todayStamp() {
+    return new Date().toISOString().slice(0, 10);
+}
+/** Append a summary block to working-memory.md, creating the file if needed. */
+function appendToWorkingMemory(slug, summary) {
+    const file = workingMemoryPath(slug);
+    mkdirSync(path.dirname(file), { recursive: true });
+    let existing = '';
+    if (existsSync(file))
+        existing = readFileSync(file, 'utf-8');
+    const appended = (existing.endsWith('\n') || existing === '' ? existing : existing + '\n')
+        + '\n'
+        + summary
+        + '\n';
+    writeFileSync(file, appended);
+}
+export function registerDecisionReflectionTools(server) {
+    server.tool('decision_reflection', 'Run a self-reflection on your recent autonomous decisions: read the proactive ledger, compute success rates per action type, identify miscalibration patterns, and surface concrete tuning suggestions. Use to spot when you are over-acting, under-acting, or going dormant. Optionally writes a summary to working-memory so your next heartbeat tick reads it as context.', {
+        slug: z.string().optional().describe('Agent slug to reflect on. Defaults to the calling agent (or "clementine" for the daemon).'),
+        window_days: z.number().optional().describe('Window in days to analyze. Default 7. Range 1-90.'),
+        save_to_history: z.boolean().optional().describe('Persist the full report to vault/00-System/agents/<slug>/reflections/<date>.md (default true).'),
+        append_to_memory: z.boolean().optional().describe('Append a compact summary to working-memory.md so the next tick reads it (default false). Be deliberate — repeated appends bloat the prompt.'),
+    }, async ({ slug, window_days, save_to_history, append_to_memory }) => {
+        const targetSlug = slug || ACTIVE_AGENT_SLUG || 'clementine';
+        const window = Math.max(1, Math.min(90, typeof window_days === 'number' ? window_days : 7));
+        const persistHistory = save_to_history !== false; // default true
+        const updateMemory = append_to_memory === true; // default false (explicit opt-in)
+        const reflection = analyzeAgentDecisions(targetSlug, window);
+        const report = formatReflectionReport(reflection);
+        const writes = [];
+        if (persistHistory) {
+            try {
+                const dir = reflectionsDir(targetSlug);
+                mkdirSync(dir, { recursive: true });
+                const file = path.join(dir, `${todayStamp()}.md`);
+                writeFileSync(file, report);
+                writes.push(`Saved to ${file}`);
+            }
+            catch (err) {
+                logger.warn({ err, slug: targetSlug }, 'Failed to save reflection history');
+                writes.push(`Failed to save history: ${String(err).slice(0, 200)}`);
+            }
+        }
+        if (updateMemory) {
+            try {
+                appendToWorkingMemory(targetSlug, formatReflectionSummary(reflection));
+                writes.push(`Appended summary to ${workingMemoryPath(targetSlug)}`);
+            }
+            catch (err) {
+                logger.warn({ err, slug: targetSlug }, 'Failed to append reflection to working-memory');
+                writes.push(`Failed to update working-memory: ${String(err).slice(0, 200)}`);
+            }
+        }
+        const footer = writes.length > 0 ? '\n\n---\n' + writes.map((w) => `- ${w}`).join('\n') : '';
+        return textResult(report + footer);
+    });
+}
+//# sourceMappingURL=decision-reflection-tools.js.map

package/dist/tools/mcp-server.js

@@ -28,6 +28,7 @@ import { registerArtifactTools } from './artifact-tools.js';
 import { registerBrainTools } from './brain-tools.js';
 import { registerAgentHeartbeatTools } from './agent-heartbeat-tools.js';
 import { registerBackgroundTaskTools } from './background-task-tools.js';
+import { registerDecisionReflectionTools } from './decision-reflection-tools.js';
 // ── Server ──────────────────────────────────────────────────────────────
 const serverName = (env['ASSISTANT_NAME'] ?? 'Clementine').toLowerCase() + '-tools';
 const server = new McpServer({ name: serverName, version: '1.0.0' });
@@ -43,6 +44,7 @@ registerArtifactTools(server);
 registerBrainTools(server);
 registerAgentHeartbeatTools(server);
 registerBackgroundTaskTools(server);
+registerDecisionReflectionTools(server);
 // ── Main ────────────────────────────────────────────────────────────────
 async function main() {
     // Initialize memory store and run full sync on startup

package/package.json

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

package/vault/00-System/CRON.md

@@ -37,6 +37,21 @@ jobs:
       4. Write a brief summary of the day in today's daily note under ## Summary
     tier: 1
     enabled: true
+
+  - name: weekly-decision-reflection
+    schedule: "0 9 * * 0"
+    prompt: >
+      Run a self-reflection on the past week's autonomous decisions.
+      1. Call `decision_reflection` with window_days=7, save_to_history=true, append_to_memory=true.
+         This reads the proactive ledger, computes per-action success rates, identifies
+         miscalibration patterns, and writes a tuning note to your working-memory so the
+         next heartbeat tick reads it as context.
+      2. For each specialist on the team (use `team_list` to enumerate), also run
+         `decision_reflection` with their slug, save_to_history=true, append_to_memory=true.
+      3. Briefly summarize in today's daily note under "## Decision reflection" — list each
+         agent's headline pattern (e.g., "Ross: act_now success 33%, raise threshold").
+    tier: 1
+    enabled: true
 tags:
   - system
   - cron
@@ -53,6 +68,7 @@ Scheduled tasks that run automatically at specific times. Edit the frontmatter a
 | morning-briefing | 8:00 AM daily | Comprehensive morning briefing |
 | weekly-review | 6:00 PM Fridays | Weekly summary + planning |
 | daily-memory-cleanup | 10:00 PM daily | Promote daily facts to long-term memory |
+| weekly-decision-reflection | 9:00 AM Sundays | Per-agent self-tuning from proactive ledger |
 
 ## Schedule Syntax