clementine-agent 1.0.0

package/dist/tools/session-tools.js

@@ -0,0 +1,146 @@
+/**
+ * Clementine TypeScript — Session & Work Discovery MCP tools.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { BASE_DIR, HANDOFFS_DIR, INBOX_DIR, TASKS_FILE, logger, textResult, todayStr, } from './shared.js';
+function ensureHandoffsDir() {
+    if (!existsSync(HANDOFFS_DIR))
+        mkdirSync(HANDOFFS_DIR, { recursive: true });
+}
+function safeSessionName(key) {
+    return key.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+export function registerSessionTools(server) {
+    server.tool('session_pause', 'Save a structured handoff file for the current session so work can be resumed later — even after context reset.', {
+        session_key: z.string().describe('Session key (e.g., "discord:user:123")'),
+        completed: z.array(z.string()).describe('What was accomplished in this session'),
+        remaining: z.array(z.string()).describe('What still needs to be done'),
+        decisions: z.array(z.string()).optional().describe('Key decisions made during this session'),
+        blockers: z.array(z.string()).optional().describe('Current blockers or open questions'),
+        context: z.string().optional().describe('Mental context — anything the resuming agent needs to know'),
+    }, async ({ session_key, completed, remaining, decisions, blockers, context }) => {
+        ensureHandoffsDir();
+        const handoff = {
+            sessionKey: session_key,
+            pausedAt: new Date().toISOString(),
+            completed, remaining,
+            decisions: decisions || [], blockers: blockers || [],
+            context: context || '',
+        };
+        const fileName = `${safeSessionName(session_key)}.json`;
+        writeFileSync(path.join(HANDOFFS_DIR, fileName), JSON.stringify(handoff, null, 2));
+        logger.info({ sessionKey: session_key, completed: completed.length, remaining: remaining.length }, 'Session handoff saved');
+        return textResult(`Handoff saved. ${completed.length} items completed, ${remaining.length} remaining.\n` +
+            `Resume with session_resume when you're ready to continue.`);
+    });
+    server.tool('session_resume', 'Load a previously saved session handoff to restore context from a paused conversation.', { session_key: z.string().describe('Session key to resume') }, async ({ session_key }) => {
+        ensureHandoffsDir();
+        const fileName = `${safeSessionName(session_key)}.json`;
+        const filePath = path.join(HANDOFFS_DIR, fileName);
+        if (!existsSync(filePath))
+            return textResult(`No handoff found for session "${session_key}". Starting fresh.`);
+        try {
+            const handoff = JSON.parse(readFileSync(filePath, 'utf-8'));
+            const sections = [`## Session Handoff (paused at ${handoff.pausedAt})`];
+            if (handoff.completed?.length > 0)
+                sections.push(`### Completed\n${handoff.completed.map((c) => `- ✓ ${c}`).join('\n')}`);
+            if (handoff.remaining?.length > 0)
+                sections.push(`### Remaining\n${handoff.remaining.map((r) => `- [ ] ${r}`).join('\n')}`);
+            if (handoff.decisions?.length > 0)
+                sections.push(`### Decisions Made\n${handoff.decisions.map((d) => `- ${d}`).join('\n')}`);
+            if (handoff.blockers?.length > 0)
+                sections.push(`### Blockers\n${handoff.blockers.map((b) => `- ⚠ ${b}`).join('\n')}`);
+            if (handoff.context)
+                sections.push(`### Context\n${handoff.context}`);
+            return textResult(sections.join('\n\n'));
+        }
+        catch {
+            return textResult(`Error reading handoff for "${session_key}".`);
+        }
+    });
+    server.tool('discover_work', 'Scan goals, tasks, inbox, and recent failures to find prioritized work items.', {
+        agent_slug: z.string().optional().describe('Filter work items for a specific agent (omit for all)'),
+        limit: z.number().optional().describe('Max items to return (default: 10)'),
+    }, async ({ agent_slug, limit }) => {
+        const maxItems = Math.min(limit ?? 10, 30);
+        const items = [];
+        // 1. Stale goals
+        const goalsDir = path.join(BASE_DIR, 'goals');
+        if (existsSync(goalsDir)) {
+            for (const f of readdirSync(goalsDir).filter(f => f.endsWith('.json'))) {
+                try {
+                    const goal = JSON.parse(readFileSync(path.join(goalsDir, f), 'utf-8'));
+                    if (goal.status !== 'active')
+                        continue;
+                    if (agent_slug && goal.owner !== agent_slug)
+                        continue;
+                    const daysSinceUpdate = Math.floor((Date.now() - new Date(goal.updatedAt).getTime()) / 86400000);
+                    const staleThreshold = goal.reviewFrequency === 'daily' ? 1 : goal.reviewFrequency === 'weekly' ? 7 : 30;
+                    if (daysSinceUpdate > staleThreshold) {
+                        const urgency = Math.min(5, Math.floor(daysSinceUpdate / staleThreshold) + (goal.priority === 'high' ? 2 : goal.priority === 'medium' ? 1 : 0));
+                        items.push({ type: 'stale-goal', urgency, description: `Goal "${goal.title}" stale for ${daysSinceUpdate}d (${goal.priority} priority)` });
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+        // 2. Failing cron jobs
+        const runDir = path.join(BASE_DIR, 'cron', 'runs');
+        if (existsSync(runDir)) {
+            for (const f of readdirSync(runDir).filter(f => f.endsWith('.jsonl'))) {
+                try {
+                    const lines = readFileSync(path.join(runDir, f), 'utf-8').trim().split('\n').filter(Boolean);
+                    const recent = lines.slice(-5).map(l => JSON.parse(l));
+                    const consecutiveErrors = recent.reverse().findIndex(r => r.status === 'ok');
+                    const errCount = consecutiveErrors === -1 ? recent.length : consecutiveErrors;
+                    if (errCount >= 2) {
+                        const jobName = recent[0]?.jobName ?? f.replace('.jsonl', '');
+                        items.push({ type: 'cron-failure', urgency: Math.min(5, errCount), description: `Job "${jobName}" has ${errCount} consecutive failures` });
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+        // 3. Pending tasks
+        if (existsSync(TASKS_FILE)) {
+            const content = readFileSync(TASKS_FILE, 'utf-8');
+            const today = todayStr();
+            const overdue = (content.match(/- \[ \].*?📅\s*(\d{4}-\d{2}-\d{2})/g) ?? [])
+                .filter(line => { const m = line.match(/📅\s*(\d{4}-\d{2}-\d{2})/); return m && m[1] < today; });
+            if (overdue.length > 0)
+                items.push({ type: 'overdue-tasks', urgency: 4, description: `${overdue.length} overdue task(s) in TASKS.md` });
+        }
+        // 4. Inbox items
+        if (existsSync(INBOX_DIR)) {
+            const inboxFiles = readdirSync(INBOX_DIR).filter(f => f.endsWith('.md') && !f.startsWith('_'));
+            if (inboxFiles.length > 0)
+                items.push({ type: 'inbox', urgency: 2, description: `${inboxFiles.length} unprocessed inbox item(s)` });
+        }
+        // 5. Daily plan priorities
+        const planFile = path.join(BASE_DIR, 'plans', 'daily', `${todayStr()}.json`);
+        if (existsSync(planFile)) {
+            try {
+                const plan = JSON.parse(readFileSync(planFile, 'utf-8'));
+                for (const p of (plan.priorities ?? []).slice(0, 5)) {
+                    const alreadyListed = items.some(i => i.description.includes(p.id) || i.description.includes(p.action?.slice(0, 20)));
+                    if (!alreadyListed)
+                        items.push({ type: `plan-${p.type}`, urgency: p.urgency ?? 3, description: `[From daily plan] ${p.action}` });
+                }
+            }
+            catch { /* non-fatal */ }
+        }
+        items.sort((a, b) => b.urgency - a.urgency);
+        const topItems = items.slice(0, maxItems);
+        if (topItems.length === 0)
+            return textResult('No work items discovered. All goals on track, no failures, inbox clear.');
+        const lines = topItems.map(i => `- [${i.type}] Urgency ${i.urgency}/5: ${i.description}`);
+        return textResult(`## Discovered Work Items (${topItems.length})\n${lines.join('\n')}`);
+    });
+}
+//# sourceMappingURL=session-tools.js.map

package/dist/tools/shared.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Clementine TypeScript — Shared MCP tool utilities.
+ *
+ * Extracted from mcp-server.ts so tool modules can import what they need.
+ * All constants, helpers, types, and lazy singletons live here.
+ */
+import pino from 'pino';
+export declare const BASE_DIR: string;
+export declare const env: Record<string, string>;
+export declare const VAULT_DIR: string;
+export declare const SYSTEM_DIR: string;
+export declare const DAILY_NOTES_DIR: string;
+export declare const PEOPLE_DIR: string;
+export declare const PROJECTS_DIR: string;
+export declare const TOPICS_DIR: string;
+export declare const TASKS_DIR: string;
+export declare const TEMPLATES_DIR: string;
+export declare const INBOX_DIR: string;
+export declare const MEMORY_FILE: string;
+export declare const WORKING_MEMORY_FILE: string;
+export declare const WORKING_MEMORY_MAX_LINES = 75;
+export declare const TASKS_FILE: string;
+export declare const SOUL_FILE: string;
+export declare const IDENTITY_FILE: string;
+export declare const HEARTBEAT_FILE: string;
+export declare const CRON_FILE: string;
+export declare const PROFILES_DIR: string;
+export declare const AGENTS_DIR: string;
+export declare const TEAM_COMMS_LOG: string;
+export declare const HANDOFFS_DIR: string;
+export declare const DELEGATIONS_BASE: string;
+export declare const logger: pino.Logger<never, boolean>;
+export type MemoryStoreType = {
+    searchFts(query: string, limit: number, filters?: {
+        category?: string;
+        topic?: string;
+    }): Array<{
+        sourceFile: string;
+        section: string;
+        content: string;
+        score: number;
+        chunkType: string;
+        matchType: string;
+        lastUpdated: string;
+        chunkId: number;
+        salience: number;
+        agentSlug?: string | null;
+        category?: string | null;
+        topic?: string | null;
+    }>;
+    getRecentChunks(limit: number, agentSlug?: string, filters?: {
+        category?: string;
+        topic?: string;
+    }): unknown[];
+    searchContext(query: string, limitOrOpts?: number | {
+        limit?: number;
+        recencyLimit?: number;
+        agentSlug?: string;
+        category?: string;
+        topic?: string;
+    }, recencyLimit?: number): unknown[];
+    getConnections(noteName: string): Array<{
+        direction: string;
+        file: string;
+        context: string;
+    }>;
+    getTimeline(startDate: string, endDate: string, limit?: number): unknown[];
+    searchTranscripts(query: string, limit?: number, sessionKey?: string): Array<{
+        sessionKey: string;
+        role: string;
+        content: string;
+        model: string;
+        createdAt: string;
+    }>;
+    fullSync(): {
+        filesScanned: number;
+        filesUpdated: number;
+        filesDeleted: number;
+        chunksTotal: number;
+    };
+    updateFile(relPath: string, agentSlug?: string): void;
+    recordAccess(chunkIds: number[]): void;
+    decaySalience(halfLifeDays?: number): number;
+    pruneStaleData(opts?: {
+        maxAgeDays?: number;
+        salienceThreshold?: number;
+        accessLogRetentionDays?: number;
+        transcriptRetentionDays?: number;
+    }): {
+        episodicPruned: number;
+        accessLogPruned: number;
+        transcriptsPruned: number;
+    };
+    checkDuplicate(content: string, sourceFile?: string): {
+        isDuplicate: boolean;
+        matchType: 'exact' | 'near' | null;
+        matchId?: number;
+    };
+    logExtraction(extraction: {
+        sessionKey: string;
+        userMessage: string;
+        toolName: string;
+        toolInput: string;
+        extractedAt: string;
+        status: string;
+        agentSlug?: string;
+    }): void;
+    getRecentExtractions(limit?: number, status?: string): Array<{
+        id: number;
+        sessionKey: string;
+        userMessage: string;
+        toolName: string;
+        toolInput: string;
+        extractedAt: string;
+        status: string;
+        correction?: string;
+    }>;
+    correctExtraction(id: number, correction: string): void;
+    dismissExtraction(id: number): void;
+    bumpChunkSalience(chunkId: number, boost?: number): void;
+    getRecentCorrections(limit?: number): Array<{
+        toolInput: string;
+        correction: string;
+    }>;
+    getConsolidationCandidates(minAgeDays?: number): Array<{
+        topic: string;
+        chunkIds: number[];
+        contents: string[];
+        totalChars: number;
+    }>;
+    markConsolidated(chunkIds: number[]): void;
+    getConsolidationStats(): {
+        totalChunks: number;
+        consolidated: number;
+        unconsolidated: number;
+    };
+    logFeedback(feedback: {
+        sessionKey?: string;
+        channel: string;
+        messageSnippet?: string;
+        responseSnippet?: string;
+        rating: string;
+        comment?: string;
+    }): void;
+    getRecentFeedback(limit?: number): Array<{
+        id: number;
+        sessionKey?: string;
+        channel: string;
+        messageSnippet?: string;
+        responseSnippet?: string;
+        rating: string;
+        comment?: string;
+        createdAt: string;
+    }>;
+    getFeedbackStats(): {
+        positive: number;
+        negative: number;
+        mixed: number;
+        total: number;
+    };
+    promoteToGlobal(chunkId: number, promotedBy?: string): string;
+    db: unknown;
+};
+export declare function getStore(): Promise<MemoryStoreType>;
+export declare function getStoreSync(): MemoryStoreType | null;
+export declare const ACTIVE_AGENT_SLUG: string | null;
+export declare const GOALS_DIR: string;
+export declare function agentTasksFile(slug: string | null): string;
+export declare function agentWorkingMemoryFile(slug: string | null): string;
+export declare function agentGoalsDir(slug: string | null): string;
+export declare function agentDailyNotesDir(slug: string | null): string;
+export declare function todayStr(): string;
+export declare function yesterdayStr(): string;
+export declare function nowTime(): string;
+export declare function timeOfDaySection(): string;
+export declare function resolvePath(name: string): string;
+export declare function validateVaultPath(relPath: string): string;
+export declare function ensureDailyNote(dateStr?: string): string;
+export declare function folderForType(noteType: string): string;
+export declare function incrementalSync(relPath: string, agentSlug?: string): Promise<void>;
+export declare function textResult(text: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare const EXTERNAL_CONTENT_TAG: string;
+export declare function externalResult(text: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare const TASK_ID_RE: RegExp;
+export declare const TASK_ID_RE_G: RegExp;
+export declare const TASK_LINE_RE: RegExp;
+export interface ParsedTask {
+    id: string;
+    text: string;
+    status: string;
+    priority: string;
+    due: string;
+    project: string;
+    assignee: string;
+    recurrence: string;
+    tags: string[];
+    checked: boolean;
+    indent: string;
+    rawLine: string;
+    isSubtask: boolean;
+}
+export declare function parseTasks(body: string): ParsedTask[];
+export declare function nextTaskId(body: string): string;
+export declare function nextDueDate(currentDue: string, recurrence: string): string;
+export declare function globMd(dir: string): string[];
+//# sourceMappingURL=shared.d.ts.map