clementine-agent 1.0.0

package/dist/channels/webhook.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Clementine TypeScript — HTTP API webhook server.
+ *
+ * Provides a REST API for programmatic access to the assistant.
+ * Uses Express with Bearer token authentication.
+ */
+import type { Gateway } from '../gateway/router.js';
+export declare function startWebhook(gateway: Gateway): Promise<void>;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/channels/webhook.js

@@ -0,0 +1,78 @@
+/**
+ * Clementine TypeScript — HTTP API webhook server.
+ *
+ * Provides a REST API for programmatic access to the assistant.
+ * Uses Express with Bearer token authentication.
+ */
+import express from 'express';
+import pino from 'pino';
+import { WEBHOOK_PORT, WEBHOOK_SECRET } from '../config.js';
+const logger = pino({ name: 'clementine.webhook' });
+// ── Entry point ───────────────────────────────────────────────────────
+export async function startWebhook(gateway) {
+    const app = express();
+    app.use(express.json());
+    // ── Bearer token auth middleware ──────────────────────────────────
+    function requireAuth(req, res, next) {
+        const authHeader = req.headers.authorization ?? '';
+        const token = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : '';
+        if (!token || token !== WEBHOOK_SECRET) {
+            res.status(401).json({ error: 'Unauthorized' });
+            return;
+        }
+        next();
+    }
+    // ── POST /api/message — process a message ─────────────────────────
+    app.post('/api/message', requireAuth, async (req, res) => {
+        const { text, session_key: sessionKey, model } = req.body;
+        if (!text) {
+            res.status(400).json({ error: 'Missing "text" field' });
+            return;
+        }
+        const effectiveSessionKey = sessionKey ?? 'webhook:default';
+        try {
+            const response = await gateway.handleMessage(effectiveSessionKey, text, undefined, model);
+            res.json({ response, session_key: effectiveSessionKey });
+        }
+        catch (err) {
+            logger.error({ err }, 'Webhook message processing failed');
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    // ── POST /webhook/:source — generic webhook intake ────────────────
+    app.post('/webhook/:source', requireAuth, async (req, res) => {
+        const source = req.params.source;
+        const body = req.body;
+        const text = String(body.text ?? body.message ?? body.content ?? JSON.stringify(body));
+        const sessionKey = `webhook:${source}`;
+        try {
+            const response = await gateway.handleMessage(sessionKey, text);
+            res.json({ response, source, session_key: sessionKey });
+        }
+        catch (err) {
+            logger.error({ err, source }, 'Webhook intake processing failed');
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    // ── GET /api/status — health check ────────────────────────────────
+    app.get('/api/status', (_req, res) => {
+        res.json({
+            status: 'ok',
+            uptime: process.uptime(),
+            timestamp: new Date().toISOString(),
+        });
+    });
+    // ── Start server ──────────────────────────────────────────────────
+    const port = WEBHOOK_PORT;
+    await new Promise((resolve) => {
+        app.listen(port, '0.0.0.0', () => {
+            logger.info(`Webhook API server listening on port ${port}`);
+            resolve();
+        });
+    });
+    // Keep alive
+    await new Promise((_, reject) => {
+        process.once('SIGTERM', () => reject(new Error('SIGTERM')));
+    });
+}
+//# sourceMappingURL=webhook.js.map

package/dist/channels/whatsapp.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Clementine TypeScript — WhatsApp channel adapter (via Twilio).
+ *
+ * Uses Express for webhook receiving and Twilio REST API for sending.
+ * Supports incoming messages with Twilio signature validation,
+ * message chunking, and markdown cleanup.
+ */
+import type { NotificationDispatcher } from '../gateway/notifications.js';
+import type { Gateway } from '../gateway/router.js';
+export declare function startWhatsApp(gateway: Gateway, dispatcher: NotificationDispatcher): Promise<void>;
+//# sourceMappingURL=whatsapp.d.ts.map

package/dist/channels/whatsapp.js

@@ -0,0 +1,181 @@
+/**
+ * Clementine TypeScript — WhatsApp channel adapter (via Twilio).
+ *
+ * Uses Express for webhook receiving and Twilio REST API for sending.
+ * Supports incoming messages with Twilio signature validation,
+ * message chunking, and markdown cleanup.
+ */
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+import express from 'express';
+import pino from 'pino';
+import { TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, WHATSAPP_OWNER_PHONE, WHATSAPP_FROM_PHONE, WHATSAPP_WEBHOOK_PORT, } from '../config.js';
+const logger = pino({ name: 'clementine.whatsapp' });
+const TWILIO_API_URL = `https://api.twilio.com/2010-04-01/Accounts/${TWILIO_ACCOUNT_SID}/Messages.json`;
+const WHATSAPP_MAX_LENGTH = 4096;
+// ── Phone hashing ─────────────────────────────────────────────────────
+function hashPhone(phone) {
+    return createHash('sha256').update(phone).digest('hex').slice(0, 12);
+}
+// ── Twilio signature validation ───────────────────────────────────────
+function validateTwilioSignature(url, params, signature, authToken) {
+    // Build the data string: URL + sorted params
+    let data = url;
+    for (const key of Object.keys(params).sort()) {
+        data += key + params[key];
+    }
+    const expected = createHmac('sha1', authToken).update(data).digest('base64');
+    // Constant-time comparison
+    try {
+        return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
+    }
+    catch {
+        return false;
+    }
+}
+// ── WhatsApp formatting ───────────────────────────────────────────────
+function cleanForWhatsApp(text) {
+    // WhatsApp supports *bold* and _italic_ natively, but not code blocks
+    text = text.replace(/\*\*/g, '*'); // markdown bold -> WhatsApp bold
+    text = text.replace(/```/g, ''); // code fences
+    text = text.replace(/`/g, ''); // inline code
+    return text;
+}
+function splitMessage(text, maxLength = WHATSAPP_MAX_LENGTH) {
+    if (text.length <= maxLength)
+        return [text];
+    const chunks = [];
+    let remaining = text;
+    while (remaining) {
+        if (remaining.length <= maxLength) {
+            chunks.push(remaining);
+            break;
+        }
+        // Find a good split point (newline or space)
+        let splitAt = remaining.lastIndexOf('\n', maxLength);
+        if (splitAt === -1 || splitAt < maxLength / 2) {
+            splitAt = remaining.lastIndexOf(' ', maxLength);
+        }
+        if (splitAt === -1 || splitAt < maxLength / 2) {
+            splitAt = maxLength;
+        }
+        chunks.push(remaining.slice(0, splitAt));
+        remaining = remaining.slice(splitAt).trimStart();
+    }
+    return chunks;
+}
+// ── Twilio REST API sending ───────────────────────────────────────────
+async function sendWhatsApp(to, body) {
+    const params = new URLSearchParams({
+        To: `whatsapp:${to}`,
+        From: `whatsapp:${WHATSAPP_FROM_PHONE}`,
+        Body: body,
+    });
+    const auth = Buffer.from(`${TWILIO_ACCOUNT_SID}:${TWILIO_AUTH_TOKEN}`).toString('base64');
+    const resp = await fetch(TWILIO_API_URL, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            'Authorization': `Basic ${auth}`,
+        },
+        body: params.toString(),
+    });
+    if (!resp.ok) {
+        const text = await resp.text();
+        logger.error(`Twilio send failed (${resp.status}): ${text.slice(0, 300)}`);
+    }
+}
+// ── Entry point ───────────────────────────────────────────────────────
+export async function startWhatsApp(gateway, dispatcher) {
+    if (!TWILIO_ACCOUNT_SID || !TWILIO_AUTH_TOKEN) {
+        logger.error('TWILIO_ACCOUNT_SID / TWILIO_AUTH_TOKEN not set — WhatsApp channel disabled');
+        return;
+    }
+    if (!WHATSAPP_OWNER_PHONE) {
+        logger.error('WHATSAPP_OWNER_PHONE not set — WhatsApp channel disabled');
+        return;
+    }
+    const ownerHash = hashPhone(WHATSAPP_OWNER_PHONE);
+    const app = express();
+    // Parse URL-encoded bodies (Twilio sends form data)
+    app.use(express.urlencoded({ extended: false }));
+    app.post('/webhook/whatsapp', async (req, res) => {
+        const params = {};
+        for (const [key, value] of Object.entries(req.body)) {
+            params[key] = String(value);
+        }
+        // Validate Twilio signature
+        const signature = req.headers['x-twilio-signature'] ?? '';
+        const requestUrl = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
+        if (!validateTwilioSignature(requestUrl, params, signature, TWILIO_AUTH_TOKEN)) {
+            logger.warn('Invalid Twilio signature — rejecting request');
+            res.status(403).send('Invalid signature');
+            return;
+        }
+        // Extract message fields
+        const body = (params.Body ?? '').trim();
+        const fromNumber = (params.From ?? '').replace('whatsapp:', '');
+        if (!fromNumber) {
+            res.status(400).send('Missing From field');
+            return;
+        }
+        // Owner-only check
+        if (fromNumber !== WHATSAPP_OWNER_PHONE) {
+            logger.warn(`Ignoring message from non-owner: ${hashPhone(fromNumber)}`);
+            res.type('application/xml').send('<Response></Response>');
+            return;
+        }
+        if (!body) {
+            res.type('application/xml').send('<Response></Response>');
+            return;
+        }
+        const sessionKey = `whatsapp:user:${ownerHash}`;
+        logger.info(`WhatsApp message: ${body.slice(0, 80)}...`);
+        // Return TwiML immediately; process in background
+        res.type('application/xml').send('<Response></Response>');
+        // Process and reply asynchronously
+        try {
+            const response = await gateway.handleMessage(sessionKey, body);
+            if (response) {
+                const clean = cleanForWhatsApp(response);
+                const chunks = splitMessage(clean);
+                for (const chunk of chunks) {
+                    await sendWhatsApp(fromNumber, chunk);
+                }
+            }
+        }
+        catch (err) {
+            logger.error({ err }, 'Error processing WhatsApp message');
+            // Don't leave the user in silence — send an error message back
+            try {
+                await sendWhatsApp(fromNumber, 'Something went wrong — try again in a moment.');
+            }
+            catch (sendErr) {
+                logger.error({ err: sendErr }, 'Failed to send WhatsApp error notification');
+            }
+        }
+    });
+    // Register notification sender
+    async function whatsappNotify(text) {
+        const clean = cleanForWhatsApp(text);
+        const chunks = splitMessage(clean);
+        for (const chunk of chunks) {
+            await sendWhatsApp(WHATSAPP_OWNER_PHONE, chunk);
+        }
+    }
+    dispatcher.register('whatsapp', whatsappNotify);
+    const port = WHATSAPP_WEBHOOK_PORT;
+    await new Promise((resolve) => {
+        app.listen(port, '0.0.0.0', () => {
+            logger.info(`WhatsApp webhook server listening on port ${port}`);
+            resolve();
+        });
+    });
+    // Keep alive — the Express server runs in the background
+    await new Promise((_, reject) => {
+        process.once('SIGTERM', () => {
+            dispatcher.unregister('whatsapp');
+            reject(new Error('SIGTERM'));
+        });
+    });
+}
+//# sourceMappingURL=whatsapp.js.map

package/dist/cli/chat.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Clementine CLI — Interactive REPL chat session.
+ *
+ * Usage: clementine chat [--model sonnet] [--project myapp] [--profile researcher]
+ *
+ * Lazy-initializes a gateway instance and streams responses to stdout.
+ * Bang commands: !model, !project, !clear, !help, !q, !d prefixes.
+ */
+export declare function cmdChat(opts: {
+    model?: string;
+    project?: string;
+    profile?: string;
+}): Promise<void>;
+//# sourceMappingURL=chat.d.ts.map

package/dist/cli/chat.js

@@ -0,0 +1,220 @@
+/**
+ * Clementine CLI — Interactive REPL chat session.
+ *
+ * Usage: clementine chat [--model sonnet] [--project myapp] [--profile researcher]
+ *
+ * Lazy-initializes a gateway instance and streams responses to stdout.
+ * Bang commands: !model, !project, !clear, !help, !q, !d prefixes.
+ */
+import readline from 'node:readline';
+import os from 'node:os';
+import path from 'node:path';
+const BASE_DIR = process.env.CLEMENTINE_HOME || path.join(os.homedir(), '.clementine');
+// ── ANSI helpers ─────────────────────────────────────────────────────
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[0;90m';
+const CYAN = '\x1b[0;36m';
+const GREEN = '\x1b[0;32m';
+const YELLOW = '\x1b[1;33m';
+const RESET = '\x1b[0m';
+/** Simple ANSI markdown renderer for terminal output. */
+function renderMarkdown(text) {
+    return text
+        // Bold
+        .replace(/\*\*(.+?)\*\*/g, `${BOLD}$1${RESET}`)
+        // Inline code
+        .replace(/`([^`]+)`/g, `${DIM}$1${RESET}`)
+        // Headers
+        .replace(/^(#{1,3})\s+(.+)$/gm, (_m, hashes, title) => {
+        const color = hashes.length === 1 ? CYAN : hashes.length === 2 ? GREEN : YELLOW;
+        return `${color}${BOLD}${title}${RESET}`;
+    });
+}
+// ── Lazy gateway init ────────────────────────────────────────────────
+let gatewayInstance = null;
+async function getGateway() {
+    if (gatewayInstance)
+        return gatewayInstance;
+    process.env.CLEMENTINE_HOME = BASE_DIR;
+    delete process.env['CLAUDECODE'];
+    const { PersonalAssistant } = await import('../agent/assistant.js');
+    const assistant = new PersonalAssistant();
+    const { Gateway: GatewayClass } = await import('../gateway/router.js');
+    gatewayInstance = new GatewayClass(assistant);
+    const { setApprovalCallback } = await import('../agent/hooks.js');
+    setApprovalCallback(async () => false);
+    return gatewayInstance;
+}
+// ── REPL ─────────────────────────────────────────────────────────────
+export async function cmdChat(opts) {
+    const sessionKey = `cli:repl:${process.pid}`;
+    console.log(`${CYAN}${BOLD}Clementine Chat${RESET} ${DIM}(Ctrl+C to exit)${RESET}`);
+    console.log();
+    const gateway = await getGateway();
+    // Apply initial model override
+    if (opts.model) {
+        const { MODELS } = await import('../config.js');
+        const tier = opts.model.toLowerCase();
+        if (tier in MODELS) {
+            gateway.setSessionModel(sessionKey, MODELS[tier]);
+            console.log(`${DIM}Model: ${tier} (${MODELS[tier]})${RESET}`);
+        }
+    }
+    // Apply initial project override
+    if (opts.project) {
+        const { findProjectByName } = await import('../agent/assistant.js');
+        const project = findProjectByName(opts.project);
+        if (project) {
+            gateway.setSessionProject(sessionKey, project);
+            console.log(`${DIM}Project: ${path.basename(project.path)}${RESET}`);
+        }
+        else {
+            console.log(`${YELLOW}Project "${opts.project}" not found — using auto-matching${RESET}`);
+        }
+    }
+    // Apply initial profile override
+    if (opts.profile) {
+        const { PROFILES_DIR, AGENTS_DIR } = await import('../config.js');
+        const { AgentManager } = await import('../agent/agent-manager.js');
+        const pm = new AgentManager(AGENTS_DIR, PROFILES_DIR);
+        const profile = pm.get(opts.profile);
+        if (profile) {
+            gateway.setSessionProfile(sessionKey, opts.profile);
+            console.log(`${DIM}Profile: ${profile.name}${RESET}`);
+        }
+        else {
+            console.log(`${YELLOW}Profile "${opts.profile}" not found${RESET}`);
+        }
+    }
+    console.log();
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        prompt: `${GREEN}>${RESET} `,
+    });
+    rl.prompt();
+    rl.on('line', async (line) => {
+        const text = line.trim();
+        if (!text) {
+            rl.prompt();
+            return;
+        }
+        // ── Bang commands ────────────────────────────────────────────
+        if (text === '!help' || text === '!h') {
+            console.log([
+                `${BOLD}Commands:${RESET}`,
+                `  ${CYAN}!model [haiku|sonnet|opus]${RESET} — Switch model`,
+                `  ${CYAN}!project <name|list|clear|status>${RESET} — Set project context`,
+                `  ${CYAN}!clear${RESET} — Reset conversation`,
+                `  ${CYAN}!q <msg>${RESET} — Quick reply (Haiku)`,
+                `  ${CYAN}!d <msg>${RESET} — Deep reply (Opus)`,
+                `  ${CYAN}!help${RESET} — This message`,
+                `  ${DIM}Ctrl+C to exit${RESET}`,
+            ].join('\n'));
+            rl.prompt();
+            return;
+        }
+        if (text === '!clear') {
+            gateway.clearSession(sessionKey);
+            console.log(`${DIM}Session cleared.${RESET}`);
+            rl.prompt();
+            return;
+        }
+        if (text.startsWith('!model')) {
+            const parts = text.split(/\s+/);
+            const tier = parts[1]?.toLowerCase();
+            const { MODELS } = await import('../config.js');
+            if (tier && tier in MODELS) {
+                gateway.setSessionModel(sessionKey, MODELS[tier]);
+                console.log(`${DIM}Model switched to ${tier} (${MODELS[tier]})${RESET}`);
+            }
+            else {
+                const current = gateway.getSessionModel(sessionKey) ?? 'default';
+                console.log(`${DIM}Current model: ${current}. Options: haiku, sonnet, opus${RESET}`);
+            }
+            rl.prompt();
+            return;
+        }
+        if (text.startsWith('!project')) {
+            const parts = text.split(/\s+/);
+            const subCmd = parts[1]?.toLowerCase();
+            if (subCmd === 'clear') {
+                gateway.clearSessionProject(sessionKey);
+                console.log(`${DIM}Project context cleared.${RESET}`);
+            }
+            else if (subCmd === 'status') {
+                const current = gateway.getSessionProject(sessionKey);
+                if (current) {
+                    console.log(`${DIM}Active: ${path.basename(current.path)} — ${current.path}${RESET}`);
+                }
+                else {
+                    console.log(`${DIM}No active project. Using auto-matching.${RESET}`);
+                }
+            }
+            else if (subCmd === 'list' || !subCmd) {
+                const { getLinkedProjects } = await import('../agent/assistant.js');
+                const projects = getLinkedProjects();
+                if (projects.length === 0) {
+                    console.log(`${DIM}No linked projects.${RESET}`);
+                }
+                else {
+                    const current = gateway.getSessionProject(sessionKey);
+                    for (const p of projects) {
+                        const name = path.basename(p.path);
+                        const active = current && p.path === current.path ? ` ${GREEN}(active)${RESET}` : '';
+                        console.log(`  ${CYAN}${name}${RESET}${active}`);
+                    }
+                }
+            }
+            else {
+                // Set project
+                const projectName = parts.slice(1).join(' ');
+                const { findProjectByName } = await import('../agent/assistant.js');
+                const project = findProjectByName(projectName);
+                if (project) {
+                    gateway.clearSession(sessionKey);
+                    gateway.setSessionProject(sessionKey, project);
+                    console.log(`${DIM}Switched to ${path.basename(project.path)}. Session cleared.${RESET}`);
+                }
+                else {
+                    console.log(`${YELLOW}Project "${projectName}" not found.${RESET}`);
+                }
+            }
+            rl.prompt();
+            return;
+        }
+        // ── Per-message model prefix ───────────────────────────────
+        let effectiveText = text;
+        let oneOffModel;
+        if (text.startsWith('!q ')) {
+            const { MODELS } = await import('../config.js');
+            oneOffModel = MODELS.haiku;
+            effectiveText = text.slice(3);
+        }
+        else if (text.startsWith('!d ')) {
+            const { MODELS } = await import('../config.js');
+            oneOffModel = MODELS.opus;
+            effectiveText = text.slice(3);
+        }
+        // ── Send message ──────────────────────────────────────────
+        process.stdout.write(`\n${DIM}thinking...${RESET}\r`);
+        try {
+            const response = await gateway.handleMessage(sessionKey, effectiveText, undefined, oneOffModel);
+            // Clear "thinking..." line
+            process.stdout.write('\x1b[2K\r');
+            console.log(renderMarkdown(response));
+            console.log();
+        }
+        catch (err) {
+            process.stdout.write('\x1b[2K\r');
+            console.error(`${YELLOW}Error: ${err}${RESET}`);
+            console.log();
+        }
+        rl.prompt();
+    });
+    rl.on('close', () => {
+        console.log(`\n${DIM}Goodbye.${RESET}`);
+        process.exit(0);
+    });
+}
+//# sourceMappingURL=chat.js.map

package/dist/cli/cron.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Clementine CLI — Standalone cron runner.
+ *
+ * Lightweight runner that initializes just the agent + gateway (no channels,
+ * no daemon), parses CRON.md, and executes a single job or heartbeat.
+ * Designed to be called by OS scheduler and exit.
+ */
+export declare function cmdCronList(): Promise<void>;
+export declare function cmdCronRun(jobName: string): Promise<void>;
+export declare function cmdCronRunDue(): Promise<void>;
+export declare function cmdCronAdd(name: string, schedule: string, prompt: string, options: {
+    tier?: string;
+}): Promise<void>;
+export declare function cmdCronTest(jobNameOrIndex: string): Promise<void>;
+export declare function cmdCronRuns(jobName?: string): Promise<void>;
+export declare function cmdHeartbeat(): Promise<void>;
+//# sourceMappingURL=cron.d.ts.map