clementine-agent 1.0.87 → 1.0.88

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/package.json

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