run-dmcp 0.1.0

package/dist/tools/narrative.js

@@ -0,0 +1,237 @@
+import { v4 as uuidv4 } from "uuid";
+import { getDatabase } from "../db/connection.js";
+import { safeJsonParse } from "../utils/json.js";
+import { gameEvents } from "../events/emitter.js";
+import { validateGameExists } from "./game.js";
+export function logEvent(params) {
+    // Validate game exists to prevent orphaned records
+    validateGameExists(params.gameId);
+    const db = getDatabase();
+    const id = uuidv4();
+    const timestamp = new Date().toISOString();
+    const stmt = db.prepare(`
+    INSERT INTO narrative_events (id, game_id, event_type, content, metadata, timestamp)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `);
+    stmt.run(id, params.gameId, params.eventType, params.content, JSON.stringify(params.metadata || {}), timestamp);
+    const event = {
+        id,
+        gameId: params.gameId,
+        eventType: params.eventType,
+        content: params.content,
+        metadata: params.metadata || {},
+        timestamp,
+    };
+    // Emit realtime event
+    gameEvents.emit({
+        type: "narrative:created",
+        gameId: params.gameId,
+        entityId: id,
+        entityType: "narrative",
+        timestamp,
+        data: event,
+    });
+    return event;
+}
+export function getEvent(id) {
+    const db = getDatabase();
+    const stmt = db.prepare(`SELECT * FROM narrative_events WHERE id = ?`);
+    const row = stmt.get(id);
+    if (!row)
+        return null;
+    return {
+        id: row.id,
+        gameId: row.game_id,
+        eventType: row.event_type,
+        content: row.content,
+        metadata: safeJsonParse(row.metadata, {}),
+        timestamp: row.timestamp,
+    };
+}
+export function getHistory(gameId, options) {
+    const db = getDatabase();
+    let query = `SELECT * FROM narrative_events WHERE game_id = ?`;
+    const params = [gameId];
+    if (options?.eventType) {
+        query += ` AND event_type = ?`;
+        params.push(options.eventType);
+    }
+    if (options?.since) {
+        query += ` AND timestamp >= ?`;
+        params.push(options.since);
+    }
+    query += ` ORDER BY timestamp DESC`;
+    if (options?.limit) {
+        query += ` LIMIT ?`;
+        params.push(options.limit);
+    }
+    if (options?.offset) {
+        query += ` OFFSET ?`;
+        params.push(options.offset);
+    }
+    const stmt = db.prepare(query);
+    const rows = stmt.all(...params);
+    // Return in chronological order
+    return rows
+        .map((row) => ({
+        id: row.id,
+        gameId: row.game_id,
+        eventType: row.event_type,
+        content: row.content,
+        metadata: safeJsonParse(row.metadata, {}),
+        timestamp: row.timestamp,
+    }))
+        .reverse();
+}
+export function getRecentHistory(gameId, count = 10) {
+    return getHistory(gameId, { limit: count });
+}
+export function getSummary(gameId) {
+    const db = getDatabase();
+    const countResult = db
+        .prepare(`SELECT COUNT(*) as count FROM narrative_events WHERE game_id = ?`)
+        .get(gameId);
+    const typeResults = db
+        .prepare(`SELECT event_type, COUNT(*) as count FROM narrative_events WHERE game_id = ? GROUP BY event_type`)
+        .all(gameId);
+    const eventTypes = {};
+    for (const row of typeResults) {
+        eventTypes[row.event_type] = row.count;
+    }
+    const firstResult = db
+        .prepare(`SELECT timestamp FROM narrative_events WHERE game_id = ? ORDER BY timestamp ASC LIMIT 1`)
+        .get(gameId);
+    const lastResult = db
+        .prepare(`SELECT timestamp FROM narrative_events WHERE game_id = ? ORDER BY timestamp DESC LIMIT 1`)
+        .get(gameId);
+    const recentEvents = getRecentHistory(gameId, 5);
+    return {
+        totalEvents: countResult.count,
+        eventTypes,
+        firstEvent: firstResult?.timestamp || null,
+        lastEvent: lastResult?.timestamp || null,
+        recentEvents,
+    };
+}
+export function deleteEvent(id) {
+    const db = getDatabase();
+    const stmt = db.prepare(`DELETE FROM narrative_events WHERE id = ?`);
+    const result = stmt.run(id);
+    return result.changes > 0;
+}
+export function clearHistory(gameId) {
+    const db = getDatabase();
+    const stmt = db.prepare(`DELETE FROM narrative_events WHERE game_id = ?`);
+    const result = stmt.run(gameId);
+    return result.changes;
+}
+export function exportStoryData(gameId, style) {
+    const db = getDatabase();
+    // Get game info
+    const game = db
+        .prepare(`SELECT name, setting, style, created_at FROM games WHERE id = ?`)
+        .get(gameId);
+    if (!game)
+        return null;
+    // Get all characters
+    const characters = db
+        .prepare(`SELECT name, is_player, notes FROM characters WHERE game_id = ?`)
+        .all(gameId);
+    // Get all locations
+    const locations = db
+        .prepare(`SELECT name, description FROM locations WHERE game_id = ?`)
+        .all(gameId);
+    // Get all quests
+    const quests = db
+        .prepare(`SELECT name, description, status, objectives FROM quests WHERE game_id = ?`)
+        .all(gameId);
+    // Get all narrative events in chronological order
+    const events = db
+        .prepare(`SELECT * FROM narrative_events WHERE game_id = ? ORDER BY timestamp ASC`)
+        .all(gameId);
+    const narrativeEvents = events.map((row) => ({
+        id: row.id,
+        gameId: row.game_id,
+        eventType: row.event_type,
+        content: row.content,
+        metadata: safeJsonParse(row.metadata, {}),
+        timestamp: row.timestamp,
+    }));
+    // Group events into chapters (by day or significant breaks)
+    const chapters = groupEventsIntoChapters(narrativeEvents);
+    return {
+        game: {
+            name: game.name,
+            setting: game.setting,
+            style: game.style,
+            createdAt: game.created_at,
+        },
+        characters: characters.map((c) => ({
+            name: c.name,
+            isPlayer: c.is_player === 1,
+            notes: c.notes,
+        })),
+        locations: locations.map((l) => ({
+            name: l.name,
+            description: l.description,
+        })),
+        quests: quests.map((q) => ({
+            name: q.name,
+            description: q.description,
+            status: q.status,
+            objectives: safeJsonParse(q.objectives, []),
+        })),
+        chapters,
+        totalEvents: narrativeEvents.length,
+        exportStyle: style,
+        instruction: getStyleInstruction(style),
+    };
+}
+function groupEventsIntoChapters(events) {
+    if (events.length === 0)
+        return [];
+    const chapters = [];
+    let currentChapter = [];
+    let currentDate = null;
+    let chapterNumber = 1;
+    for (const event of events) {
+        const eventDate = event.timestamp.split("T")[0];
+        // Start new chapter on day change or after major events
+        const isMajorEvent = ["quest_completed", "combat_resolved", "location_change"].includes(event.eventType);
+        if (currentDate && (eventDate !== currentDate || (isMajorEvent && currentChapter.length > 5))) {
+            if (currentChapter.length > 0) {
+                chapters.push({
+                    title: `Chapter ${chapterNumber}`,
+                    events: currentChapter,
+                });
+                chapterNumber++;
+                currentChapter = [];
+            }
+        }
+        currentChapter.push(event);
+        currentDate = eventDate;
+    }
+    // Add final chapter
+    if (currentChapter.length > 0) {
+        chapters.push({
+            title: `Chapter ${chapterNumber}`,
+            events: currentChapter,
+        });
+    }
+    return chapters;
+}
+function getStyleInstruction(style) {
+    const styles = {
+        "literary-fiction": "Write in a sophisticated, literary style with rich prose, deep character introspection, and thematic depth. Focus on the human condition and emotional truth.",
+        "pulp-adventure": "Write in an exciting, fast-paced pulp style with vivid action, bold heroes, and thrilling cliffhangers. Keep it punchy and entertaining.",
+        "epic-fantasy": "Write in a grand, sweeping epic fantasy style with rich world-building, dramatic moments, and mythic undertones. Channel Tolkien and Jordan.",
+        "noir": "Write in a hardboiled noir style with terse prose, moral ambiguity, and atmospheric descriptions. First person works well here.",
+        "horror": "Write in an atmospheric horror style building dread and tension. Focus on the unsettling and the unknown. Use restraint for maximum effect.",
+        "comedic": "Write in a witty, humorous style finding the absurdity and comedy in the events. Include clever dialogue and amusing observations.",
+        "young-adult": "Write in an accessible, engaging young adult style with relatable characters and clear prose. Balance action with emotional moments.",
+        "screenplay": "Format as a screenplay with scene headings, action lines, and dialogue. Focus on visual storytelling and crisp dialogue.",
+        "journal": "Write as personal journal entries from the protagonist's perspective. Intimate, reflective, and immediate.",
+        "chronicle": "Write as a historical chronicle, documenting events with a sense of importance and legacy. Slightly formal, sweeping in scope.",
+    };
+    return styles[style] || `Write the story in a ${style} style. Transform the game events into engaging narrative prose that captures the spirit of the adventure.`;
+}

package/dist/tools/notes.d.ts

@@ -0,0 +1,41 @@
+import type { Note } from "../types/index.js";
+export declare function createNote(params: {
+    gameId: string;
+    title: string;
+    content: string;
+    category?: string;
+    relatedEntityId?: string;
+    relatedEntityType?: string;
+    tags?: string[];
+    pinned?: boolean;
+}): Note;
+export declare function getNote(id: string): Note | null;
+export declare function updateNote(id: string, updates: {
+    title?: string;
+    content?: string;
+    category?: string | null;
+    relatedEntityId?: string | null;
+    relatedEntityType?: string | null;
+    tags?: string[];
+}): Note | null;
+export declare function deleteNote(id: string): boolean;
+export declare function listNotes(gameId: string, filter?: {
+    category?: string;
+    pinned?: boolean;
+    tag?: string;
+    relatedEntityId?: string;
+}): Note[];
+export declare function searchNotes(gameId: string, query: string): Note[];
+export declare function pinNote(id: string, pinned: boolean): Note | null;
+/**
+ * Modify note tags - add and/or remove tags in a single call.
+ */
+export declare function modifyNoteTags(id: string, params: {
+    add?: string[];
+    remove?: string[];
+}): {
+    note: Note;
+    added: string[];
+    removed: string[];
+} | null;
+export declare function generateRecap(gameId: string, eventLimit?: number): Note;

package/dist/tools/notes.js

@@ -0,0 +1,220 @@
+import { v4 as uuidv4 } from "uuid";
+import { getDatabase } from "../db/connection.js";
+import { safeJsonParse } from "../utils/json.js";
+import { validateGameExists } from "./game.js";
+import { getHistory } from "./narrative.js";
+export function createNote(params) {
+    // Validate game exists to prevent orphaned records
+    validateGameExists(params.gameId);
+    const db = getDatabase();
+    const id = uuidv4();
+    const now = new Date().toISOString();
+    db.prepare(`
+    INSERT INTO notes (id, game_id, title, content, category, pinned, related_entity_id, related_entity_type, tags, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(id, params.gameId, params.title, params.content, params.category || null, params.pinned ? 1 : 0, params.relatedEntityId || null, params.relatedEntityType || null, JSON.stringify(params.tags || []), now, now);
+    return {
+        id,
+        gameId: params.gameId,
+        title: params.title,
+        content: params.content,
+        category: params.category || null,
+        pinned: params.pinned || false,
+        relatedEntityId: params.relatedEntityId || null,
+        relatedEntityType: params.relatedEntityType || null,
+        tags: params.tags || [],
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+export function getNote(id) {
+    const db = getDatabase();
+    const row = db.prepare(`SELECT * FROM notes WHERE id = ?`).get(id);
+    if (!row)
+        return null;
+    return {
+        id: row.id,
+        gameId: row.game_id,
+        title: row.title,
+        content: row.content,
+        category: row.category,
+        pinned: row.pinned === 1,
+        relatedEntityId: row.related_entity_id,
+        relatedEntityType: row.related_entity_type,
+        tags: safeJsonParse(row.tags || "[]", []),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+export function updateNote(id, updates) {
+    const db = getDatabase();
+    const current = getNote(id);
+    if (!current)
+        return null;
+    const now = new Date().toISOString();
+    const newTitle = updates.title ?? current.title;
+    const newContent = updates.content ?? current.content;
+    const newCategory = updates.category !== undefined ? updates.category : current.category;
+    const newRelatedId = updates.relatedEntityId !== undefined ? updates.relatedEntityId : current.relatedEntityId;
+    const newRelatedType = updates.relatedEntityType !== undefined ? updates.relatedEntityType : current.relatedEntityType;
+    const newTags = updates.tags ?? current.tags;
+    db.prepare(`
+    UPDATE notes
+    SET title = ?, content = ?, category = ?, related_entity_id = ?, related_entity_type = ?, tags = ?, updated_at = ?
+    WHERE id = ?
+  `).run(newTitle, newContent, newCategory, newRelatedId, newRelatedType, JSON.stringify(newTags), now, id);
+    return {
+        ...current,
+        title: newTitle,
+        content: newContent,
+        category: newCategory,
+        relatedEntityId: newRelatedId,
+        relatedEntityType: newRelatedType,
+        tags: newTags,
+        updatedAt: now,
+    };
+}
+export function deleteNote(id) {
+    const db = getDatabase();
+    const result = db.prepare(`DELETE FROM notes WHERE id = ?`).run(id);
+    return result.changes > 0;
+}
+export function listNotes(gameId, filter) {
+    const db = getDatabase();
+    let query = `SELECT * FROM notes WHERE game_id = ?`;
+    const params = [gameId];
+    if (filter?.category) {
+        query += ` AND category = ?`;
+        params.push(filter.category);
+    }
+    if (filter?.pinned !== undefined) {
+        query += ` AND pinned = ?`;
+        params.push(filter.pinned ? 1 : 0);
+    }
+    if (filter?.relatedEntityId) {
+        query += ` AND related_entity_id = ?`;
+        params.push(filter.relatedEntityId);
+    }
+    query += ` ORDER BY pinned DESC, updated_at DESC`;
+    let rows = db.prepare(query).all(...params);
+    // Filter by tag in memory (since it's a JSON array)
+    if (filter?.tag) {
+        const tagToMatch = filter.tag;
+        rows = rows.filter(row => {
+            const tags = safeJsonParse(row.tags || "[]", []);
+            return tags.includes(tagToMatch);
+        });
+    }
+    return rows.map(row => ({
+        id: row.id,
+        gameId: row.game_id,
+        title: row.title,
+        content: row.content,
+        category: row.category,
+        pinned: row.pinned === 1,
+        relatedEntityId: row.related_entity_id,
+        relatedEntityType: row.related_entity_type,
+        tags: safeJsonParse(row.tags || "[]", []),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    }));
+}
+export function searchNotes(gameId, query) {
+    const db = getDatabase();
+    const searchPattern = `%${query}%`;
+    const rows = db.prepare(`
+    SELECT * FROM notes
+    WHERE game_id = ? AND (title LIKE ? OR content LIKE ?)
+    ORDER BY pinned DESC, updated_at DESC
+  `).all(gameId, searchPattern, searchPattern);
+    return rows.map(row => ({
+        id: row.id,
+        gameId: row.game_id,
+        title: row.title,
+        content: row.content,
+        category: row.category,
+        pinned: row.pinned === 1,
+        relatedEntityId: row.related_entity_id,
+        relatedEntityType: row.related_entity_type,
+        tags: safeJsonParse(row.tags || "[]", []),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    }));
+}
+export function pinNote(id, pinned) {
+    const db = getDatabase();
+    const note = getNote(id);
+    if (!note)
+        return null;
+    const now = new Date().toISOString();
+    db.prepare(`UPDATE notes SET pinned = ?, updated_at = ? WHERE id = ?`)
+        .run(pinned ? 1 : 0, now, id);
+    return { ...note, pinned, updatedAt: now };
+}
+/**
+ * Modify note tags - add and/or remove tags in a single call.
+ */
+export function modifyNoteTags(id, params) {
+    const db = getDatabase();
+    const note = getNote(id);
+    if (!note)
+        return null;
+    let tags = [...note.tags];
+    const added = [];
+    const removed = [];
+    // Remove tags first
+    if (params.remove) {
+        for (const tag of params.remove) {
+            if (tags.includes(tag)) {
+                tags = tags.filter(t => t !== tag);
+                removed.push(tag);
+            }
+        }
+    }
+    // Add new tags
+    if (params.add) {
+        for (const tag of params.add) {
+            if (!tags.includes(tag)) {
+                tags.push(tag);
+                added.push(tag);
+            }
+        }
+    }
+    const now = new Date().toISOString();
+    db.prepare(`UPDATE notes SET tags = ?, updated_at = ? WHERE id = ?`)
+        .run(JSON.stringify(tags), now, id);
+    return { note: { ...note, tags, updatedAt: now }, added, removed };
+}
+export function generateRecap(gameId, eventLimit = 20) {
+    // Get recent narrative events
+    const events = getHistory(gameId, { limit: eventLimit });
+    // Group by type for summary
+    const byType = {};
+    for (const event of events) {
+        if (!byType[event.eventType]) {
+            byType[event.eventType] = [];
+        }
+        byType[event.eventType].push(event.content);
+    }
+    // Build recap content
+    let content = "# Game Recap\n\n";
+    content += `*Generated from last ${events.length} events*\n\n`;
+    for (const [eventType, contents] of Object.entries(byType)) {
+        content += `## ${eventType.charAt(0).toUpperCase() + eventType.slice(1)}\n\n`;
+        for (const c of contents.slice(0, 5)) {
+            content += `- ${c.slice(0, 200)}${c.length > 200 ? "..." : ""}\n`;
+        }
+        if (contents.length > 5) {
+            content += `- *(and ${contents.length - 5} more...)*\n`;
+        }
+        content += "\n";
+    }
+    // Create the note
+    return createNote({
+        gameId,
+        title: `Game Recap - ${new Date().toLocaleDateString()}`,
+        content,
+        category: "recap",
+        tags: ["auto-generated", "recap"],
+    });
+}

package/dist/tools/pause.d.ts

@@ -0,0 +1,110 @@
+import type { PauseState, PauseChecklist, ResumeContext, NarrativeThread, ActiveConversation, ExternalUpdate, PendingUpdatesResult } from "../types/index.js";
+/**
+ * Prepares for a game pause by returning current state, a comprehensive
+ * game state audit, persistence reminders, and a checklist of context
+ * that should be saved. This helps agents understand what needs to be
+ * captured before ending a game.
+ */
+export declare function preparePause(gameId: string): PauseChecklist | null;
+export interface SavePauseStateParams {
+    gameId: string;
+    currentScene: string;
+    immediateSituation: string;
+    sceneAtmosphere?: string;
+    pendingPlayerAction?: string;
+    awaitingResponseTo?: string;
+    presentedChoices?: string[];
+    activeThreads?: NarrativeThread[];
+    dmShortTermPlans?: string;
+    dmLongTermPlans?: string;
+    upcomingReveals?: string[];
+    npcAttitudes?: Record<string, string>;
+    activeConversations?: ActiveConversation[];
+    recentTone?: string;
+    playerApparentGoals?: string;
+    unresolvedHooks?: string[];
+    pauseReason?: string;
+    modelUsed?: string;
+}
+export declare function savePauseState(params: SavePauseStateParams): PauseState;
+export declare function getPauseState(gameId: string): PauseState | null;
+/**
+ * Returns everything needed to resume a paused game seamlessly.
+ * Includes pause state, full game state, and a ready-to-use resume prompt.
+ */
+export declare function getResumeContext(gameId: string): ResumeContext | null;
+export interface ContextSnapshotParams {
+    gameId: string;
+    situation: string;
+    notes?: string;
+    npcMood?: Record<string, string>;
+    playerIntent?: string;
+}
+/**
+ * Quick, lightweight context save for use during play.
+ * Agents should call this after significant moments.
+ * Updates only the most volatile fields without full pause ceremony.
+ */
+export declare function saveContextSnapshot(params: ContextSnapshotParams): {
+    success: boolean;
+    message: string;
+    suggestion?: string;
+};
+export declare function deletePauseState(gameId: string): boolean;
+/**
+ * Returns a reminder if context hasn't been saved recently.
+ * Use this to nudge agents to save context during long sessions.
+ */
+export declare function checkContextFreshness(gameId: string): {
+    needsSave: boolean;
+    lastSaved: string | null;
+    minutesSinceLastSave: number | null;
+    suggestion: string;
+};
+export interface PushUpdateParams {
+    gameId: string;
+    sourceAgent: string;
+    sourceDescription?: string;
+    updateType: string;
+    category?: string;
+    title: string;
+    content: string;
+    structuredData?: Record<string, unknown>;
+    targetEntityId?: string;
+    targetEntityType?: string;
+    priority?: "low" | "normal" | "high" | "urgent";
+}
+/**
+ * Push an update from an external agent (research agent, worldbuilder, etc.)
+ * The primary DM agent will receive this update and can incorporate it.
+ */
+export declare function pushExternalUpdate(params: PushUpdateParams): ExternalUpdate;
+/**
+ * Get all pending updates for a game.
+ * Call this to check for new information from external agents.
+ */
+export declare function getPendingUpdates(gameId: string): PendingUpdatesResult;
+/**
+ * Acknowledge an update (mark as seen by DM).
+ */
+export declare function acknowledgeUpdate(updateId: string): ExternalUpdate | null;
+/**
+ * Mark an update as applied (incorporated into the narrative).
+ */
+export declare function applyUpdate(updateId: string, dmNotes?: string): ExternalUpdate | null;
+/**
+ * Reject an update (not appropriate for the narrative).
+ */
+export declare function rejectUpdate(updateId: string, dmNotes?: string): ExternalUpdate | null;
+/**
+ * Get a specific external update by ID.
+ */
+export declare function getExternalUpdate(updateId: string): ExternalUpdate | null;
+/**
+ * List all updates for a game with optional status filter.
+ */
+export declare function listExternalUpdates(gameId: string, status?: ExternalUpdate["status"]): ExternalUpdate[];
+/**
+ * Delete an external update.
+ */
+export declare function deleteExternalUpdate(updateId: string): boolean;