clementine-agent 1.0.86 → 1.0.88

package/dist/agent/background-tasks.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Clementine TypeScript — Background task persistence + lifecycle helpers.
+ *
+ * A "background task" is an unleashed multi-turn job that an agent kicks
+ * off via the `start_background_task` MCP tool. Persistence is one JSON
+ * file per task at ~/.clementine/background-tasks/<id>.json. The file is
+ * the source of truth — the MCP tool writes the initial pending state,
+ * the daemon picks it up, runs it, and updates the same file as the
+ * lifecycle progresses.
+ *
+ * Process boundary: the MCP tool runs in an SDK subprocess, so it can't
+ * call the gateway directly. It writes a pending file; the daemon's
+ * cron-scheduler tick picks up pending tasks within ~3 seconds.
+ *
+ * Restart safety: on daemon startup, any task left in 'running' is
+ * aborted (its process is gone). P6b can add resumability; for now,
+ * fail-fast is clearer than silently re-running a task that may have
+ * already partially completed.
+ */
+import type { BackgroundTask } from '../types.js';
+export declare const BACKGROUND_TASK_DIR: string;
+export interface BackgroundTaskOptions {
+    /** Override storage directory for tests. Defaults to BASE_DIR/background-tasks/. */
+    dir?: string;
+}
+/**
+ * Create a new pending task on disk and return it. Caller (the MCP tool)
+ * doesn't await execution — the daemon picks the task up asynchronously.
+ */
+export declare function createBackgroundTask(input: {
+    fromAgent: string;
+    prompt: string;
+    maxMinutes: number;
+}, opts?: BackgroundTaskOptions): BackgroundTask;
+/** Load a task by id, or null if not found / malformed. */
+export declare function loadBackgroundTask(id: string, opts?: BackgroundTaskOptions): BackgroundTask | null;
+/** List tasks with optional status / agent filters, newest first. */
+export declare function listBackgroundTasks(filter?: {
+    status?: BackgroundTask['status'];
+    fromAgent?: string;
+}, opts?: BackgroundTaskOptions): BackgroundTask[];
+/** Transition a task to 'running' — daemon picked it up. */
+export declare function markRunning(id: string, opts?: BackgroundTaskOptions): BackgroundTask | null;
+/** Transition to 'done' with final result. */
+export declare function markDone(id: string, result: string, deliverableNote?: string, opts?: BackgroundTaskOptions): BackgroundTask | null;
+/** Transition to 'failed' or 'aborted' with error message. */
+export declare function markFailed(id: string, error: string, reason?: 'failed' | 'aborted', opts?: BackgroundTaskOptions): BackgroundTask | null;
+/**
+ * Daemon-restart hygiene: any task still in 'running' must be from a
+ * prior daemon process. Mark them aborted so the lifecycle is honest.
+ * Returns the count of tasks aborted.
+ */
+export declare function abortStaleRunningTasks(opts?: BackgroundTaskOptions): number;
+/** Test-only: delete a task file. Production code never deletes — history matters. */
+export declare function _deleteBackgroundTask(id: string, opts?: BackgroundTaskOptions): void;
+//# sourceMappingURL=background-tasks.d.ts.map

package/dist/agent/background-tasks.js

@@ -0,0 +1,159 @@
+/**
+ * Clementine TypeScript — Background task persistence + lifecycle helpers.
+ *
+ * A "background task" is an unleashed multi-turn job that an agent kicks
+ * off via the `start_background_task` MCP tool. Persistence is one JSON
+ * file per task at ~/.clementine/background-tasks/<id>.json. The file is
+ * the source of truth — the MCP tool writes the initial pending state,
+ * the daemon picks it up, runs it, and updates the same file as the
+ * lifecycle progresses.
+ *
+ * Process boundary: the MCP tool runs in an SDK subprocess, so it can't
+ * call the gateway directly. It writes a pending file; the daemon's
+ * cron-scheduler tick picks up pending tasks within ~3 seconds.
+ *
+ * Restart safety: on daemon startup, any task left in 'running' is
+ * aborted (its process is gone). P6b can add resumability; for now,
+ * fail-fast is clearer than silently re-running a task that may have
+ * already partially completed.
+ */
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+import { BASE_DIR } from '../config.js';
+const DEFAULT_DIR = path.join(BASE_DIR, 'background-tasks');
+const RESULT_TRUNCATE_BYTES = 3000;
+export const BACKGROUND_TASK_DIR = DEFAULT_DIR;
+function dirFor(opts) {
+    return opts?.dir ?? DEFAULT_DIR;
+}
+function makeId(now = new Date()) {
+    // Sortable-by-time prefix + 6 hex chars of randomness
+    return `bg-${now.getTime().toString(36)}-${randomBytes(3).toString('hex')}`;
+}
+function pathFor(id, opts) {
+    return path.join(dirFor(opts), `${id}.json`);
+}
+function safeWrite(file, task) {
+    mkdirSync(path.dirname(file), { recursive: true });
+    // Truncate result so a runaway task can't blow the file size
+    const slim = task.result && task.result.length > RESULT_TRUNCATE_BYTES
+        ? { ...task, result: task.result.slice(0, RESULT_TRUNCATE_BYTES) + '\n...[truncated]' }
+        : task;
+    writeFileSync(file, JSON.stringify(slim, null, 2));
+}
+/**
+ * Create a new pending task on disk and return it. Caller (the MCP tool)
+ * doesn't await execution — the daemon picks the task up asynchronously.
+ */
+export function createBackgroundTask(input, opts) {
+    const now = new Date();
+    const task = {
+        id: makeId(now),
+        fromAgent: input.fromAgent,
+        prompt: input.prompt,
+        maxMinutes: Math.max(1, Math.min(240, Math.floor(input.maxMinutes))), // 1m–4h
+        status: 'pending',
+        createdAt: now.toISOString(),
+    };
+    safeWrite(pathFor(task.id, opts), task);
+    return task;
+}
+/** Load a task by id, or null if not found / malformed. */
+export function loadBackgroundTask(id, opts) {
+    try {
+        const file = pathFor(id, opts);
+        if (!existsSync(file))
+            return null;
+        return JSON.parse(readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** List tasks with optional status / agent filters, newest first. */
+export function listBackgroundTasks(filter = {}, opts) {
+    const dir = dirFor(opts);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    let files;
+    try {
+        files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    for (const file of files) {
+        try {
+            const task = JSON.parse(readFileSync(path.join(dir, file), 'utf-8'));
+            if (filter.status && task.status !== filter.status)
+                continue;
+            if (filter.fromAgent && task.fromAgent !== filter.fromAgent)
+                continue;
+            out.push(task);
+        }
+        catch { /* skip malformed */ }
+    }
+    // Newest first by createdAt; falls back to id (which is timestamp-prefixed)
+    out.sort((a, b) => (b.createdAt ?? '').localeCompare(a.createdAt ?? ''));
+    return out;
+}
+/** Transition a task to 'running' — daemon picked it up. */
+export function markRunning(id, opts) {
+    const task = loadBackgroundTask(id, opts);
+    if (!task)
+        return null;
+    task.status = 'running';
+    task.startedAt = new Date().toISOString();
+    safeWrite(pathFor(id, opts), task);
+    return task;
+}
+/** Transition to 'done' with final result. */
+export function markDone(id, result, deliverableNote, opts) {
+    const task = loadBackgroundTask(id, opts);
+    if (!task)
+        return null;
+    task.status = 'done';
+    task.completedAt = new Date().toISOString();
+    task.result = result;
+    if (deliverableNote)
+        task.deliverableNote = deliverableNote;
+    safeWrite(pathFor(id, opts), task);
+    return task;
+}
+/** Transition to 'failed' or 'aborted' with error message. */
+export function markFailed(id, error, reason = 'failed', opts) {
+    const task = loadBackgroundTask(id, opts);
+    if (!task)
+        return null;
+    task.status = reason;
+    task.completedAt = new Date().toISOString();
+    task.error = error.slice(0, 1000);
+    safeWrite(pathFor(id, opts), task);
+    return task;
+}
+/**
+ * Daemon-restart hygiene: any task still in 'running' must be from a
+ * prior daemon process. Mark them aborted so the lifecycle is honest.
+ * Returns the count of tasks aborted.
+ */
+export function abortStaleRunningTasks(opts) {
+    const stuck = listBackgroundTasks({ status: 'running' }, opts);
+    let aborted = 0;
+    for (const t of stuck) {
+        markFailed(t.id, 'daemon restarted while task was in flight', 'aborted', opts);
+        aborted++;
+    }
+    return aborted;
+}
+/** Test-only: delete a task file. Production code never deletes — history matters. */
+export function _deleteBackgroundTask(id, opts) {
+    try {
+        const file = pathFor(id, opts);
+        if (existsSync(file))
+            unlinkSync(file);
+    }
+    catch { /* ignore */ }
+}
+//# sourceMappingURL=background-tasks.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,57 @@ 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');
+            const tasks = listBackgroundTasks();
+            const now = Date.now();
+            // Add derived fields convenient for UI use
+            const out = tasks.map((t) => {
+                const startedMs = t.startedAt ? new Date(t.startedAt).getTime() : 0;
+                const completedMs = t.completedAt ? new Date(t.completedAt).getTime() : 0;
+                return {
+                    ...t,
+                    runningForMs: t.status === 'running' && startedMs > 0 ? now - startedMs : null,
+                    totalDurationMs: startedMs > 0 && completedMs > 0 ? completedMs - startedMs : null,
+                };
+            });
+            res.json(out);
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err).slice(0, 200) });
+        }
+    });
     app.get('/api/heartbeat/agent/:slug', (req, res) => {
         const slug = req.params.slug;
         const state = getHeartbeat();

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

@@ -150,6 +150,17 @@ export declare class CronScheduler {
     private unwatchWorkflowDir;
     /** Watch the triggers directory for MCP-initiated job runs and goal work sessions. */
     private watchTriggers;
+    /**
+     * Pick up pending background tasks and run them via the unleashed
+     * cron path. Each task gets the originating agent's profile and
+     * Discord channel for the completion notification.
+     *
+     * Concurrency: a task moves from 'pending' to 'running' synchronously
+     * before the long-running work starts, so a second tick won't pick up
+     * the same task twice. Failures are logged + persisted; we never throw
+     * out of the trigger interval.
+     */
+    private processBackgroundTasks;
     /** Process any pending trigger files and run the corresponding jobs. */
     private processTriggers;
     /** Process any pending goal work trigger files. Routes through the execution advisor. */

package/dist/gateway/cron-scheduler.js

@@ -18,6 +18,7 @@ import { scanner } from '../security/scanner.js';
 import { parseAllWorkflows as parseAllWorkflowsSync } from '../agent/workflow-runner.js';
 import { SelfImproveLoop } from '../agent/self-improve.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';
 const logger = pino({ name: 'clementine.cron' });
 /** Default timeout for standard cron jobs (10 minutes). */
@@ -1501,8 +1502,73 @@ export class CronScheduler {
         this.triggerTimer = setInterval(() => {
             this.processTriggers();
             this.processGoalTriggers();
+            this.processBackgroundTasks();
         }, 3000);
     }
+    /**
+     * Pick up pending background tasks and run them via the unleashed
+     * cron path. Each task gets the originating agent's profile and
+     * Discord channel for the completion notification.
+     *
+     * Concurrency: a task moves from 'pending' to 'running' synchronously
+     * before the long-running work starts, so a second tick won't pick up
+     * the same task twice. Failures are logged + persisted; we never throw
+     * out of the trigger interval.
+     */
+    processBackgroundTasks() {
+        let pending;
+        try {
+            pending = listBackgroundTasks({ status: 'pending' });
+        }
+        catch {
+            return;
+        }
+        if (pending.length === 0)
+            return;
+        for (const task of pending) {
+            // Move to 'running' synchronously so the next tick (3s away) won't
+            // re-pick. Even if the work below errors, the state is honest.
+            const started = markBgTaskRunning(task.id);
+            if (!started)
+                continue;
+            logger.info({ id: task.id, fromAgent: task.fromAgent, maxMinutes: task.maxMinutes }, 'Background task picked up');
+            // Don't await — fire-and-forget. The 3s tick continues to scan.
+            const jobName = `bg:${task.id}`;
+            const maxHours = Math.max(0.05, task.maxMinutes / 60);
+            this.gateway.handleCronJob(jobName, task.prompt, 2, // tier 2 (Bash/Write/Edit available)
+            undefined, // default maxTurns
+            undefined, // default model
+            undefined, // default workDir
+            'unleashed', // long-running mode
+            maxHours, undefined, // timeoutMs (maxHours covers it)
+            undefined, // successCriteria
+            task.fromAgent).then((result) => {
+                try {
+                    markBgTaskDone(task.id, result ?? '(no output)');
+                }
+                catch (err) {
+                    logger.warn({ err, id: task.id }, 'Failed to mark background task done');
+                }
+                // Dispatch the deliverable to the originating agent's channel.
+                const deliveryHead = `**Background task ${task.id} done** — ${task.prompt.slice(0, 100).replace(/\s+/g, ' ')}${task.prompt.length > 100 ? '...' : ''}\n\n`;
+                const body = (result ?? '').slice(0, 1500);
+                this.dispatcher
+                    .send(deliveryHead + body, { agentSlug: task.fromAgent !== 'clementine' ? task.fromAgent : undefined })
+                    .catch((err) => logger.debug({ err, id: task.id }, 'Failed to dispatch background task result'));
+            }).catch((err) => {
+                const errStr = String(err).slice(0, 500);
+                try {
+                    markBgTaskFailed(task.id, errStr, 'failed');
+                }
+                catch (saveErr) {
+                    logger.warn({ err: saveErr, id: task.id }, 'Failed to mark background task failed');
+                }
+                this.dispatcher
+                    .send(`**Background task ${task.id} failed** — ${errStr.slice(0, 200)}`, { agentSlug: task.fromAgent !== 'clementine' ? task.fromAgent : undefined })
+                    .catch(() => { });
+            });
+        }
+    }
     /** Process any pending trigger files and run the corresponding jobs. */
     processTriggers() {
         if (!existsSync(this.triggerDir))

package/dist/index.js

@@ -762,6 +762,19 @@ async function asyncMain() {
     heartbeat.start();
     cronScheduler.start();
     agentHeartbeats.start();
+    // Background-task hygiene: any task left in 'running' is from a prior
+    // process. Mark them aborted so the lifecycle is honest. (P6b will add
+    // resumability; for now fail-fast is clearer than silently re-running.)
+    try {
+        const { abortStaleRunningTasks } = await import('./agent/background-tasks.js');
+        const aborted = abortStaleRunningTasks();
+        if (aborted > 0) {
+            logger.info({ count: aborted }, 'Aborted stale running background tasks from prior daemon');
+        }
+    }
+    catch (err) {
+        logger.warn({ err }, 'Background task hygiene check failed — non-fatal');
+    }
     const timerInterval = startTimerChecker(dispatcher, gateway);
     // Start brain ingest scheduler (polls registered REST sources on their cron)
     try {

package/dist/tools/background-task-tools.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Clementine TypeScript — Background task MCP tools.
+ *
+ * `start_background_task` lets an agent kick off a long-running job
+ * (research, multi-page extraction, batch outreach) without blocking
+ * the conversation. The agent gets a task id immediately and is
+ * notified in their channel when the work completes.
+ *
+ * Internally: the tool writes a pending task file. The daemon's
+ * cron-scheduler tick picks it up within ~3 seconds, runs it via
+ * runUnleashedTask with the agent's profile, then dispatches the
+ * result to the agent's Discord channel.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerBackgroundTaskTools(server: McpServer): void;
+//# sourceMappingURL=background-task-tools.d.ts.map

package/dist/tools/background-task-tools.js

@@ -0,0 +1,105 @@
+/**
+ * Clementine TypeScript — Background task MCP tools.
+ *
+ * `start_background_task` lets an agent kick off a long-running job
+ * (research, multi-page extraction, batch outreach) without blocking
+ * the conversation. The agent gets a task id immediately and is
+ * notified in their channel when the work completes.
+ *
+ * Internally: the tool writes a pending task file. The daemon's
+ * cron-scheduler tick picks it up within ~3 seconds, runs it via
+ * runUnleashedTask with the agent's profile, then dispatches the
+ * result to the agent's Discord channel.
+ */
+import { z } from 'zod';
+import { createBackgroundTask, listBackgroundTasks, loadBackgroundTask, } from '../agent/background-tasks.js';
+import { ACTIVE_AGENT_SLUG, logger, textResult } from './shared.js';
+const DEFAULT_MAX_MINUTES = 30;
+export function registerBackgroundTaskTools(server) {
+    server.tool('start_background_task', 'Kick off a long-running autonomous task in the background. Use when the work would burn the chat context (deep research, multi-page extraction, batch processing) or take longer than a chat turn. Returns a task id immediately. The daemon picks the task up within seconds, runs it with your profile + tools, and posts the deliverable to your Discord channel when done.', {
+        prompt: z.string().describe('The full task description — be specific about what you want produced. Use the same level of detail you would give a teammate.'),
+        max_minutes: z.number().optional().describe(`Hard wall-clock cap on the task. Default ${DEFAULT_MAX_MINUTES} min. Range 1–240. Use longer caps for sustained research.`),
+    }, async ({ prompt, max_minutes }) => {
+        const fromAgent = ACTIVE_AGENT_SLUG || 'clementine';
+        const trimmed = (prompt ?? '').trim();
+        if (!trimmed) {
+            return textResult('start_background_task: prompt is required.');
+        }
+        const cap = typeof max_minutes === 'number' ? max_minutes : DEFAULT_MAX_MINUTES;
+        const task = createBackgroundTask({
+            fromAgent,
+            prompt: trimmed,
+            maxMinutes: cap,
+        });
+        logger.info({ id: task.id, fromAgent, maxMinutes: task.maxMinutes }, 'Background task queued');
+        return textResult(`Queued **${task.id}** (max ${task.maxMinutes} min). The daemon will pick it up within a few seconds and run it in the background. You'll get a notification in your channel when the deliverable lands. Use \`get_background_task\` to check status.`);
+    });
+    server.tool('get_background_task', 'Check the status of a background task. Returns its lifecycle state (pending|running|done|failed|aborted), how long it has been running, and the result/error if terminal.', {
+        task_id: z.string().describe('Task id returned by start_background_task (e.g., "bg-abc123-def4")'),
+    }, async ({ task_id }) => {
+        const task = loadBackgroundTask(task_id);
+        if (!task) {
+            return textResult(`get_background_task: no task found with id "${task_id}".`);
+        }
+        const lines = [];
+        lines.push(`**${task.id}** — ${task.status}`);
+        lines.push(`From: ${task.fromAgent}`);
+        lines.push(`Created: ${task.createdAt}`);
+        if (task.startedAt)
+            lines.push(`Started: ${task.startedAt}`);
+        if (task.completedAt)
+            lines.push(`Completed: ${task.completedAt}`);
+        lines.push(`Max minutes: ${task.maxMinutes}`);
+        lines.push('');
+        lines.push(`Prompt: ${task.prompt.slice(0, 300)}${task.prompt.length > 300 ? '...' : ''}`);
+        if (task.status === 'running' && task.startedAt) {
+            const elapsedMin = Math.round((Date.now() - new Date(task.startedAt).getTime()) / 60000);
+            lines.push('');
+            lines.push(`Running for ${elapsedMin}m / ${task.maxMinutes}m cap.`);
+        }
+        if (task.error) {
+            lines.push('');
+            lines.push(`Error: ${task.error}`);
+        }
+        if (task.result) {
+            lines.push('');
+            lines.push(`Result:\n${task.result}`);
+        }
+        if (task.deliverableNote) {
+            lines.push('');
+            lines.push(`Deliverable: ${task.deliverableNote}`);
+        }
+        return textResult(lines.join('\n'));
+    });
+    server.tool('list_background_tasks', 'List background tasks, optionally filtered by status or originating agent. Newest first. Use to see what work is in flight or completed recently.', {
+        status: z
+            .enum(['pending', 'running', 'done', 'failed', 'aborted'])
+            .optional()
+            .describe('Filter by lifecycle status'),
+        from_agent: z.string().optional().describe('Filter by originating agent slug'),
+        limit: z.number().optional().describe('Max number to return (default 20, max 100)'),
+    }, async ({ status, from_agent, limit }) => {
+        const filter = {};
+        if (status)
+            filter.status = status;
+        if (from_agent)
+            filter.fromAgent = from_agent;
+        const all = listBackgroundTasks(filter);
+        const cap = Math.max(1, Math.min(100, typeof limit === 'number' ? limit : 20));
+        const tasks = all.slice(0, cap);
+        if (tasks.length === 0) {
+            const filterDesc = [
+                status ? `status=${status}` : '',
+                from_agent ? `from_agent=${from_agent}` : '',
+            ].filter(Boolean).join(', ');
+            return textResult(`No background tasks found${filterDesc ? ` (${filterDesc})` : ''}.`);
+        }
+        const lines = [`## Background tasks (${tasks.length}${all.length > tasks.length ? ` of ${all.length}` : ''})`];
+        for (const t of tasks) {
+            const promptHead = t.prompt.replace(/\s+/g, ' ').slice(0, 80);
+            lines.push(`- **${t.id}** [${t.status}] ${t.fromAgent}: ${promptHead}${t.prompt.length > 80 ? '...' : ''}`);
+        }
+        return textResult(lines.join('\n'));
+    });
+}
+//# sourceMappingURL=background-task-tools.js.map

package/dist/tools/mcp-server.js

@@ -27,6 +27,7 @@ import { registerSessionTools } from './session-tools.js';
 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';
 // ── Server ──────────────────────────────────────────────────────────────
 const serverName = (env['ASSISTANT_NAME'] ?? 'Clementine').toLowerCase() + '-tools';
 const server = new McpServer({ name: serverName, version: '1.0.0' });
@@ -41,6 +42,7 @@ registerSessionTools(server);
 registerArtifactTools(server);
 registerBrainTools(server);
 registerAgentHeartbeatTools(server);
+registerBackgroundTaskTools(server);
 // ── Main ────────────────────────────────────────────────────────────────
 async function main() {
     // Initialize memory store and run full sync on startup

package/dist/types.d.ts

@@ -239,6 +239,30 @@ export interface HeartbeatWorkItem {
     error?: string;
     agentSlug?: string;
 }
+/**
+ * Long-running autonomous task an agent kicks off via the
+ * `start_background_task` MCP tool. The task runs in the daemon as an
+ * unleashed cron-style job with the requesting agent's profile, then
+ * notifies that agent's Discord channel on completion.
+ *
+ * Lifecycle: pending → running → (done | failed | aborted)
+ *
+ * Persisted as ~/.clementine/background-tasks/<id>.json. The file is
+ * the source of truth; status is updated in place as the task progresses.
+ */
+export interface BackgroundTask {
+    id: string;
+    fromAgent: string;
+    prompt: string;
+    maxMinutes: number;
+    status: 'pending' | 'running' | 'done' | 'failed' | 'aborted';
+    createdAt: string;
+    startedAt?: string;
+    completedAt?: string;
+    result?: string;
+    error?: string;
+    deliverableNote?: string;
+}
 /**
  * State for one specialist agent's heartbeat scheduler. Persisted at
  * ~/.clementine/heartbeat/agents/<slug>/state.json. Manager reads

package/package.json

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