clementine-agent 1.0.0

package/dist/tools/goal-tools.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Clementine TypeScript — Goal MCP tools.
+ *
+ * Persistent goals that drive proactive agent behavior and
+ * can be linked to cron jobs for autonomous progress.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerGoalTools(server: McpServer): void;
+//# sourceMappingURL=goal-tools.d.ts.map

package/dist/tools/goal-tools.js

@@ -0,0 +1,159 @@
+/**
+ * Clementine TypeScript — Goal MCP tools.
+ *
+ * Persistent goals that drive proactive agent behavior and
+ * can be linked to cron jobs for autonomous progress.
+ */
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { BASE_DIR, logger, textResult } from './shared.js';
+const GOALS_DIR = path.join(BASE_DIR, 'goals');
+const GOAL_TRIGGER_DIR = path.join(BASE_DIR, 'cron', 'goal-triggers');
+function ensureGoalsDir() {
+    if (!existsSync(GOALS_DIR))
+        mkdirSync(GOALS_DIR, { recursive: true });
+}
+export function registerGoalTools(server) {
+    server.tool('goal_create', 'Create a new persistent goal that survives across sessions. Goals drive proactive agent behavior and can be linked to cron jobs.', {
+        title: z.string().describe('Short goal title'),
+        description: z.string().describe('Detailed description of what this goal aims to achieve'),
+        owner: z.string().optional().describe('Agent slug that owns this goal (default: "clementine")'),
+        priority: z.enum(['high', 'medium', 'low']).optional().describe('Priority level (default: "medium")'),
+        targetDate: z.string().optional().describe('Target completion date (YYYY-MM-DD)'),
+        nextActions: z.array(z.string()).optional().describe('Initial next actions to take'),
+        reviewFrequency: z.enum(['daily', 'weekly', 'on-demand']).optional().describe('How often to review (default: "weekly")'),
+        linkedCronJobs: z.array(z.string()).optional().describe('Cron job names that contribute to this goal'),
+        autoSchedule: z.boolean().optional().describe('Allow the daily planner to auto-create/adjust cron jobs for this goal (default: false)'),
+    }, async ({ title, description, owner, priority, targetDate, nextActions, reviewFrequency, linkedCronJobs, autoSchedule }) => {
+        ensureGoalsDir();
+        const id = randomBytes(4).toString('hex');
+        const now = new Date().toISOString();
+        const goal = {
+            id, title, description,
+            status: 'active',
+            owner: owner || 'clementine',
+            priority: priority || 'medium',
+            createdAt: now, updatedAt: now, targetDate,
+            progressNotes: [],
+            nextActions: nextActions || [],
+            blockers: [],
+            reviewFrequency: reviewFrequency || 'weekly',
+            linkedCronJobs: linkedCronJobs || [],
+            ...(autoSchedule ? { autoSchedule } : {}),
+        };
+        writeFileSync(path.join(GOALS_DIR, `${id}.json`), JSON.stringify(goal, null, 2));
+        logger.info({ goalId: id, title }, 'Goal created');
+        return textResult(`Goal created: "${title}" (ID: ${id})`);
+    });
+    server.tool('goal_update', 'Update an existing persistent goal — add progress notes, change status, update next actions, or add blockers.', {
+        id: z.string().describe('Goal ID'),
+        status: z.enum(['active', 'paused', 'completed', 'blocked']).optional().describe('New status'),
+        progressNote: z.string().optional().describe('Progress note to append (what was accomplished)'),
+        nextActions: z.array(z.string()).optional().describe('Replace next actions list'),
+        blockers: z.array(z.string()).optional().describe('Replace blockers list'),
+        linkedCronJobs: z.array(z.string()).optional().describe('Replace linked cron jobs'),
+        priority: z.enum(['high', 'medium', 'low']).optional().describe('Change priority'),
+        autoSchedule: z.boolean().optional().describe('Allow the daily planner to auto-create/adjust cron jobs for this goal'),
+    }, async ({ id, status, progressNote, nextActions, blockers, linkedCronJobs, priority, autoSchedule }) => {
+        const filePath = path.join(GOALS_DIR, `${id}.json`);
+        if (!existsSync(filePath))
+            return textResult(`Goal not found: ${id}`);
+        const goal = JSON.parse(readFileSync(filePath, 'utf-8'));
+        if (status)
+            goal.status = status;
+        if (progressNote)
+            goal.progressNotes.push(`[${new Date().toISOString().slice(0, 16)}] ${progressNote}`);
+        if (nextActions)
+            goal.nextActions = nextActions;
+        if (blockers)
+            goal.blockers = blockers;
+        if (linkedCronJobs)
+            goal.linkedCronJobs = linkedCronJobs;
+        if (priority)
+            goal.priority = priority;
+        if (autoSchedule !== undefined)
+            goal.autoSchedule = autoSchedule;
+        goal.updatedAt = new Date().toISOString();
+        writeFileSync(filePath, JSON.stringify(goal, null, 2));
+        logger.info({ goalId: id, status: goal.status }, 'Goal updated');
+        return textResult(`Goal "${goal.title}" updated (status: ${goal.status})`);
+    });
+    server.tool('goal_list', 'List persistent goals, optionally filtered by owner or status.', {
+        owner: z.string().optional().describe('Filter by owner agent slug'),
+        status: z.enum(['active', 'paused', 'completed', 'blocked']).optional().describe('Filter by status'),
+    }, async ({ owner, status }) => {
+        ensureGoalsDir();
+        const files = readdirSync(GOALS_DIR).filter(f => f.endsWith('.json'));
+        let goals = files.map(f => {
+            try {
+                return JSON.parse(readFileSync(path.join(GOALS_DIR, f), 'utf-8'));
+            }
+            catch {
+                return null;
+            }
+        }).filter(Boolean);
+        if (owner)
+            goals = goals.filter((g) => g.owner === owner);
+        if (status)
+            goals = goals.filter((g) => g.status === status);
+        if (goals.length === 0)
+            return textResult('No goals found matching the criteria.');
+        const lines = goals.map((g) => {
+            const nextAct = g.nextActions?.length > 0 ? ` | Next: ${g.nextActions[0]}` : '';
+            const linked = g.linkedCronJobs?.length > 0 ? ` | Crons: ${g.linkedCronJobs.join(', ')}` : '';
+            return `- [${g.status.toUpperCase()}] **${g.title}** (${g.id}) — ${g.priority} priority, owner: ${g.owner}${nextAct}${linked}`;
+        });
+        return textResult(`Goals (${goals.length}):\n${lines.join('\n')}`);
+    });
+    server.tool('goal_get', 'Get a single persistent goal with full history — progress notes, next actions, blockers, and linked cron jobs.', { id: z.string().describe('Goal ID') }, async ({ id }) => {
+        const filePath = path.join(GOALS_DIR, `${id}.json`);
+        if (!existsSync(filePath))
+            return textResult(`Goal not found: ${id}`);
+        const goal = JSON.parse(readFileSync(filePath, 'utf-8'));
+        const sections = [
+            `# ${goal.title}`,
+            `**ID:** ${goal.id} | **Status:** ${goal.status} | **Priority:** ${goal.priority} | **Owner:** ${goal.owner}`,
+            `**Created:** ${goal.createdAt} | **Updated:** ${goal.updatedAt}${goal.targetDate ? ` | **Target:** ${goal.targetDate}` : ''}`,
+            `**Review:** ${goal.reviewFrequency}`,
+            `\n## Description\n${goal.description}`,
+        ];
+        if (goal.progressNotes?.length > 0)
+            sections.push(`\n## Progress Notes\n${goal.progressNotes.map((n) => `- ${n}`).join('\n')}`);
+        if (goal.nextActions?.length > 0)
+            sections.push(`\n## Next Actions\n${goal.nextActions.map((a) => `- [ ] ${a}`).join('\n')}`);
+        if (goal.blockers?.length > 0)
+            sections.push(`\n## Blockers\n${goal.blockers.map((b) => `- ${b}`).join('\n')}`);
+        if (goal.linkedCronJobs?.length > 0)
+            sections.push(`\n## Linked Cron Jobs\n${goal.linkedCronJobs.map((c) => `- ${c}`).join('\n')}`);
+        return textResult(sections.join('\n'));
+    });
+    server.tool('goal_work', 'Spawn a focused background work session on a specific goal. The daemon picks up the trigger and runs a goal-directed session asynchronously — results are delivered via notifications.', {
+        goal_id: z.string().describe('ID of the goal to work on'),
+        focus: z.string().optional().describe('Specific aspect to focus on. Defaults to the goal\'s first nextAction.'),
+        max_turns: z.number().optional().default(15).describe('Max agent turns for this work session'),
+    }, async ({ goal_id, focus, max_turns }) => {
+        ensureGoalsDir();
+        const goalPath = path.join(GOALS_DIR, `${goal_id}.json`);
+        if (!existsSync(goalPath))
+            return textResult(`Goal not found: ${goal_id}. Use goal_list to see available goals.`);
+        const goal = JSON.parse(readFileSync(goalPath, 'utf-8'));
+        if (goal.status !== 'active')
+            return textResult(`Goal "${goal.title}" is ${goal.status} — only active goals can be worked on.`);
+        mkdirSync(GOAL_TRIGGER_DIR, { recursive: true });
+        const trigger = {
+            goalId: goal_id,
+            focus: focus || goal.nextActions?.[0] || goal.description,
+            maxTurns: max_turns,
+            triggeredAt: new Date().toISOString(),
+        };
+        const triggerFile = path.join(GOAL_TRIGGER_DIR, `${Date.now()}-${goal_id}.trigger.json`);
+        writeFileSync(triggerFile, JSON.stringify(trigger, null, 2));
+        logger.info({ goalId: goal_id, focus: trigger.focus }, 'Goal work session triggered');
+        return textResult(`Triggered goal work session for "${goal.title}" (${goal_id}).\n` +
+            `Focus: ${trigger.focus}\n` +
+            `The daemon will pick it up within a few seconds. Results delivered via notifications.`);
+    });
+}
+//# sourceMappingURL=goal-tools.js.map

package/dist/tools/mcp-server.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Clementine TypeScript — MCP stdio server entry point.
+ *
+ * All tool implementations live in separate modules.
+ * This file handles server initialization, startup sync, user tools,
+ * plugins, and the stdio transport connection.
+ *
+ * Usage:
+ *   npx tsx src/tools/mcp-server.ts
+ */
+export { getStore, textResult, externalResult, incrementalSync, ACTIVE_AGENT_SLUG } from './shared.js';
+export type { MemoryStoreType } from './shared.js';
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/tools/mcp-server.js

@@ -0,0 +1,141 @@
+/**
+ * Clementine TypeScript — MCP stdio server entry point.
+ *
+ * All tool implementations live in separate modules.
+ * This file handles server initialization, startup sync, user tools,
+ * plugins, and the stdio transport connection.
+ *
+ * Usage:
+ *   npx tsx src/tools/mcp-server.ts
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { BASE_DIR, VAULT_DIR, env, getStore, getStoreSync, logger, textResult, externalResult, } from './shared.js';
+// Re-export for any code that imports from mcp-server.ts directly
+export { getStore, textResult, externalResult, incrementalSync, ACTIVE_AGENT_SLUG } from './shared.js';
+// ── Tool modules ────────────────────────────────────────────────────────
+import { registerMemoryTools } from './memory-tools.js';
+import { registerVaultTools } from './vault-tools.js';
+import { registerExternalTools } from './external-tools.js';
+import { registerAdminTools } from './admin-tools.js';
+import { registerGoalTools } from './goal-tools.js';
+import { registerTeamTools } from './team-tools.js';
+import { registerSessionTools } from './session-tools.js';
+// ── Server ──────────────────────────────────────────────────────────────
+const serverName = (env['ASSISTANT_NAME'] ?? 'Clementine').toLowerCase() + '-tools';
+const server = new McpServer({ name: serverName, version: '1.0.0' });
+// Register all tool groups
+registerMemoryTools(server);
+registerVaultTools(server);
+registerExternalTools(server);
+registerAdminTools(server);
+registerGoalTools(server);
+registerTeamTools(server);
+registerSessionTools(server);
+// ── Main ────────────────────────────────────────────────────────────────
+async function main() {
+    // Initialize memory store and run full sync on startup
+    try {
+        const store = await getStore();
+        const stats = store.fullSync();
+        logger.info({ filesScanned: stats.filesScanned, filesUpdated: stats.filesUpdated, chunksTotal: stats.chunksTotal }, 'Startup sync complete');
+        const decayed = store.decaySalience();
+        const pruned = store.pruneStaleData();
+        if (decayed > 0 || pruned.episodicPruned > 0 || pruned.accessLogPruned > 0 || pruned.transcriptsPruned > 0) {
+            logger.info({ decayed, ...pruned }, 'Startup maintenance complete');
+        }
+    }
+    catch (err) {
+        logger.warn({ err }, 'Startup sync failed (non-fatal)');
+    }
+    // Graceful shutdown
+    const shutdown = (signal) => {
+        logger.info({ signal }, 'MCP server shutting down');
+        try {
+            const s = getStoreSync();
+            if (s && typeof s.close === 'function')
+                s.close();
+        }
+        catch { /* */ }
+        process.exit(0);
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    // Auto-register user tool scripts from ~/.clementine/tools/
+    const userToolsDir = path.join(BASE_DIR, 'tools');
+    if (existsSync(userToolsDir)) {
+        for (const file of readdirSync(userToolsDir).filter(f => f.endsWith('.sh') || f.endsWith('.py'))) {
+            const toolName = file.replace(/\.(sh|py)$/, '').replace(/[^a-z0-9_]/gi, '_');
+            const filePath = path.join(userToolsDir, file);
+            const metaPath = filePath + '.meta.json';
+            let desc = `Custom tool: ${toolName}`;
+            let argsDesc = 'Optional arguments string';
+            if (existsSync(metaPath)) {
+                try {
+                    const meta = JSON.parse(readFileSync(metaPath, 'utf-8'));
+                    desc = meta.description || desc;
+                    argsDesc = meta.args_description || argsDesc;
+                }
+                catch { /* defaults */ }
+            }
+            else {
+                try {
+                    const firstLines = readFileSync(filePath, 'utf-8').split('\n').slice(0, 3);
+                    const commentLine = firstLines.find(l => l.startsWith('#') && !l.startsWith('#!'));
+                    if (commentLine)
+                        desc = commentLine.slice(1).trim();
+                }
+                catch { /* default */ }
+            }
+            try {
+                server.tool(toolName, desc, { args: z.string().optional().describe(argsDesc) }, async ({ args }) => {
+                    const { execSync } = await import('node:child_process');
+                    try {
+                        const result = execSync(`"${filePath}" ${args || ''}`, {
+                            encoding: 'utf-8', timeout: 30000, cwd: BASE_DIR,
+                            env: { ...process.env, CLEMENTINE_HOME: BASE_DIR },
+                        });
+                        return textResult(result.trim() || '(no output)');
+                    }
+                    catch (err) {
+                        return textResult(`Tool error: ${err.stderr || err.message || String(err)}`.slice(0, 500));
+                    }
+                });
+                logger.info({ tool: toolName, file }, 'Registered user tool');
+            }
+            catch (err) {
+                logger.warn({ tool: toolName, err }, 'Failed to register user tool');
+            }
+        }
+    }
+    // Auto-register plugin modules from ~/.clementine/plugins/
+    const pluginsDir = path.join(BASE_DIR, 'plugins');
+    if (existsSync(pluginsDir)) {
+        for (const file of readdirSync(pluginsDir).filter(f => f.endsWith('.js') || f.endsWith('.mjs'))) {
+            try {
+                const plugin = await import(path.join(pluginsDir, file));
+                if (typeof plugin.register === 'function') {
+                    await plugin.register(server, z, { textResult, externalResult, getStore, BASE_DIR, VAULT_DIR, logger });
+                    logger.info({ plugin: file }, 'Loaded plugin');
+                }
+                else {
+                    logger.warn({ plugin: file }, 'Plugin missing register() export — skipped');
+                }
+            }
+            catch (err) {
+                logger.warn({ err, plugin: file }, 'Failed to load plugin');
+            }
+        }
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info('MCP server connected via stdio');
+}
+main().catch(err => {
+    logger.fatal({ err }, 'MCP server failed to start');
+    process.exit(1);
+});
+//# sourceMappingURL=mcp-server.js.map

package/dist/tools/memory-tools.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Clementine TypeScript — Memory MCP tools.
+ *
+ * working_memory, memory_read/write/search/recall, memory_connections,
+ * memory_timeline, transcript_search, memory_report/correct/consolidate,
+ * graph memory tools
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerMemoryTools(server: McpServer): void;
+//# sourceMappingURL=memory-tools.d.ts.map