clementine-agent 1.0.85 → 1.0.87

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/route-classifier.d.ts

@@ -23,6 +23,8 @@ export interface RouteDecision {
     confidence: number;
     reasoning: string;
 }
+/** Test-only: reset the cache between runs. */
+export declare function _resetRouteCache(): void;
 export declare function isDirectImperative(userMessage: string): {
     match: boolean;
     pattern?: string;

package/dist/agent/route-classifier.js

@@ -18,6 +18,49 @@
  */
 import pino from 'pino';
 const logger = pino({ name: 'clementine.route-classifier' });
+// ── LRU cache for repeated messages ──────────────────────────────────
+// Same text + same available-agents set → same decision. Skips the
+// Haiku LLM call entirely on cache hit (saves 1-2 seconds per repeat).
+// Bounded by both size and TTL so stale rosters can't cause wrong routes.
+const ROUTE_CACHE_MAX = 100;
+const ROUTE_CACHE_TTL_MS = 5 * 60 * 1000;
+// Insertion-ordered Map = LRU when we delete-and-reinsert on hit.
+const routeCache = new Map();
+function cacheKey(text, agents) {
+    // Trim + normalize whitespace so trailing-newline variations of the
+    // same message hit the same cache entry.
+    const normText = text.replace(/\s+/g, ' ').trim();
+    // Sort slugs so order doesn't matter; include count to invalidate on
+    // hire/fire (the agents array changes shape).
+    const slugFingerprint = agents.map(a => a.slug).sort().join(',');
+    return `${slugFingerprint}::${normText}`;
+}
+function cacheGet(key, now) {
+    const entry = routeCache.get(key);
+    if (!entry)
+        return null;
+    if (entry.expiresAt <= now) {
+        routeCache.delete(key);
+        return null;
+    }
+    // LRU touch: remove + re-insert to move to end of insertion order
+    routeCache.delete(key);
+    routeCache.set(key, entry);
+    return entry;
+}
+function cachePut(key, decision, now) {
+    routeCache.set(key, { decision, expiresAt: now + ROUTE_CACHE_TTL_MS });
+    while (routeCache.size > ROUTE_CACHE_MAX) {
+        const oldest = routeCache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        routeCache.delete(oldest);
+    }
+}
+/** Test-only: reset the cache between runs. */
+export function _resetRouteCache() {
+    routeCache.clear();
+}
 /**
  * Direct-imperative guardrail.
  *
@@ -229,6 +272,15 @@ export async function classifyRoute(userMessage, agents, gateway) {
         logger.debug({ trigger: 'question-opener' }, 'Routing skipped — question-opener');
         return null;
     }
+    // Cache hit short-circuit — same message + same roster as a recent
+    // call gets the same decision without firing the Haiku classifier.
+    const now = Date.now();
+    const key = cacheKey(userMessage, agents);
+    const hit = cacheGet(key, now);
+    if (hit) {
+        logger.debug({ trigger: 'cache-hit', cachedAgent: hit.decision?.targetAgent ?? 'clementine' }, 'Route classifier cache hit');
+        return hit.decision;
+    }
     // LLM classifier for everything else.
     const prompt = buildPrompt(userMessage, agents);
     let raw;
@@ -239,6 +291,7 @@ export async function classifyRoute(userMessage, agents, gateway) {
     }
     catch (err) {
         logger.warn({ err }, 'Route classifier call failed');
+        // Don't cache failures — next call should retry the LLM.
         return null;
     }
     const decision = parseResponse(raw);
@@ -254,6 +307,7 @@ export async function classifyRoute(userMessage, agents, gateway) {
         decision.targetAgent = 'clementine';
         decision.confidence = Math.min(decision.confidence, 0.3);
     }
+    cachePut(key, decision, now);
     return decision;
 }
 //# sourceMappingURL=route-classifier.js.map

package/dist/cli/dashboard.js

@@ -1978,6 +1978,27 @@ export async function cmdDashboard(opts) {
     app.get('/api/agent-heartbeats', (_req, res) => {
         res.json(getAgentHeartbeats());
     });
+    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.85",
+  "version": "1.0.87",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",