run-dmcp 0.1.0

package/dist/tools/quest.d.ts

@@ -0,0 +1,34 @@
+import type { Quest, QuestObjective } from "../types/index.js";
+export declare function createQuest(params: {
+    gameId: string;
+    name: string;
+    description: string;
+    objectives: Omit<QuestObjective, "id">[];
+    rewards?: string;
+}): Quest;
+export declare function getQuest(id: string): Quest | null;
+export declare function updateQuest(id: string, updates: {
+    name?: string;
+    description?: string;
+    status?: Quest["status"];
+    rewards?: string;
+}): Quest | null;
+/**
+ * Modify quest objectives - add new objectives and/or complete existing ones in a single call.
+ */
+export declare function modifyObjectives(questId: string, params: {
+    add?: Array<{
+        description: string;
+        optional?: boolean;
+    }>;
+    complete?: string[];
+}): {
+    quest: Quest;
+    added: QuestObjective[];
+    completed: string[];
+} | null;
+export declare function deleteQuest(id: string): boolean;
+export declare function listQuests(gameId: string, filter?: {
+    status?: Quest["status"];
+}): Quest[];
+export declare function getActiveQuests(gameId: string): Quest[];

package/dist/tools/quest.js

@@ -0,0 +1,164 @@
+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 createQuest(params) {
+    // Validate game exists to prevent orphaned records
+    validateGameExists(params.gameId);
+    const db = getDatabase();
+    const id = uuidv4();
+    const objectives = params.objectives.map((obj) => ({
+        id: uuidv4(),
+        description: obj.description,
+        completed: obj.completed || false,
+        optional: obj.optional,
+    }));
+    const stmt = db.prepare(`
+    INSERT INTO quests (id, game_id, name, description, objectives, status, rewards)
+    VALUES (?, ?, ?, ?, ?, 'active', ?)
+  `);
+    stmt.run(id, params.gameId, params.name, params.description, JSON.stringify(objectives), params.rewards || null);
+    return {
+        id,
+        gameId: params.gameId,
+        name: params.name,
+        description: params.description,
+        objectives,
+        status: "active",
+        rewards: params.rewards,
+    };
+}
+export function getQuest(id) {
+    const db = getDatabase();
+    const stmt = db.prepare(`SELECT * FROM quests WHERE id = ?`);
+    const row = stmt.get(id);
+    if (!row)
+        return null;
+    return {
+        id: row.id,
+        gameId: row.game_id,
+        name: row.name,
+        description: row.description,
+        objectives: safeJsonParse(row.objectives, []),
+        status: row.status,
+        rewards: row.rewards,
+    };
+}
+export function updateQuest(id, updates) {
+    const db = getDatabase();
+    const current = getQuest(id);
+    if (!current)
+        return null;
+    const newName = updates.name ?? current.name;
+    const newDescription = updates.description ?? current.description;
+    const newStatus = updates.status ?? current.status;
+    const newRewards = updates.rewards ?? current.rewards;
+    const stmt = db.prepare(`
+    UPDATE quests SET name = ?, description = ?, status = ?, rewards = ? WHERE id = ?
+  `);
+    stmt.run(newName, newDescription, newStatus, newRewards || null, id);
+    const updated = {
+        ...current,
+        name: newName,
+        description: newDescription,
+        status: newStatus,
+        rewards: newRewards,
+    };
+    // Emit realtime event
+    gameEvents.emit({
+        type: "quest:updated",
+        gameId: current.gameId,
+        entityId: id,
+        entityType: "quest",
+        timestamp: new Date().toISOString(),
+        data: { name: newName, status: newStatus },
+    });
+    return updated;
+}
+/**
+ * Modify quest objectives - add new objectives and/or complete existing ones in a single call.
+ */
+export function modifyObjectives(questId, params) {
+    const db = getDatabase();
+    const quest = getQuest(questId);
+    if (!quest)
+        return null;
+    const objectives = [...quest.objectives];
+    const added = [];
+    const completed = [];
+    // Complete objectives first
+    if (params.complete) {
+        for (const objectiveId of params.complete) {
+            const idx = objectives.findIndex((o) => o.id === objectiveId);
+            if (idx !== -1 && !objectives[idx].completed) {
+                objectives[idx] = { ...objectives[idx], completed: true };
+                completed.push(objectiveId);
+            }
+        }
+    }
+    // Add new objectives
+    if (params.add) {
+        for (const obj of params.add) {
+            const newObjective = {
+                id: uuidv4(),
+                description: obj.description,
+                completed: false,
+                optional: obj.optional,
+            };
+            objectives.push(newObjective);
+            added.push(newObjective);
+        }
+    }
+    // Check if all required objectives are complete
+    const requiredComplete = objectives
+        .filter((o) => !o.optional)
+        .every((o) => o.completed);
+    const shouldComplete = requiredComplete && quest.status === "active";
+    const newStatus = shouldComplete ? "completed" : quest.status;
+    // Update objectives and status atomically in a single statement
+    const stmt = db.prepare(`UPDATE quests SET objectives = ?, status = ? WHERE id = ?`);
+    stmt.run(JSON.stringify(objectives), newStatus, questId);
+    // Emit event if quest was completed
+    if (shouldComplete) {
+        gameEvents.emit({
+            type: "quest:updated",
+            gameId: quest.gameId,
+            entityId: questId,
+            entityType: "quest",
+            timestamp: new Date().toISOString(),
+            data: { name: quest.name, status: "completed" },
+        });
+    }
+    const finalQuest = { ...quest, objectives, status: newStatus };
+    return { quest: finalQuest, added, completed };
+}
+export function deleteQuest(id) {
+    const db = getDatabase();
+    const stmt = db.prepare(`DELETE FROM quests WHERE id = ?`);
+    const result = stmt.run(id);
+    return result.changes > 0;
+}
+export function listQuests(gameId, filter) {
+    const db = getDatabase();
+    let query = `SELECT * FROM quests WHERE game_id = ?`;
+    const params = [gameId];
+    if (filter?.status) {
+        query += ` AND status = ?`;
+        params.push(filter.status);
+    }
+    const stmt = db.prepare(query);
+    const rows = stmt.all(...params);
+    return rows.map((row) => ({
+        id: row.id,
+        gameId: row.game_id,
+        name: row.name,
+        description: row.description,
+        objectives: safeJsonParse(row.objectives, []),
+        status: row.status,
+        rewards: row.rewards,
+    }));
+}
+export function getActiveQuests(gameId) {
+    return listQuests(gameId, { status: "active" });
+}

package/dist/tools/relationship.d.ts

@@ -0,0 +1,74 @@
+import type { Relationship, RelationshipChange } from "../types/index.js";
+export declare function createRelationship(params: {
+    gameId: string;
+    sourceId: string;
+    sourceType: string;
+    targetId: string;
+    targetType: string;
+    relationshipType: string;
+    value?: number;
+    label?: string;
+    notes?: string;
+}): Relationship;
+export declare function getRelationship(id: string): Relationship | null;
+export declare function getRelationshipBetween(gameId: string, sourceId: string, targetId: string, relationshipType?: string): Relationship | null;
+export declare function updateRelationship(id: string, updates: {
+    relationshipType?: string;
+    value?: number;
+    label?: string | null;
+    notes?: string;
+}): Relationship | null;
+export declare function modifyRelationship(params: {
+    relationshipId: string;
+    delta: number;
+    reason?: string;
+    minValue?: number;
+    maxValue?: number;
+}): {
+    relationship: Relationship;
+    change: RelationshipChange;
+} | null;
+export declare function deleteRelationship(id: string): boolean;
+export declare function listRelationships(gameId: string, filter?: {
+    entityId?: string;
+    sourceId?: string;
+    targetId?: string;
+    relationshipType?: string;
+    entityType?: string;
+}): Relationship[];
+export declare function getRelationshipHistory(relationshipId: string, limit?: number): RelationshipChange[];
+/**
+ * Update a relationship value with optional metadata changes. Supports both direct set and delta modes.
+ * Logs to history when value changes.
+ */
+export declare function updateRelationshipValue(params: {
+    relationshipId: string;
+    mode: "delta" | "set";
+    value: number;
+    reason?: string;
+    minValue?: number;
+    maxValue?: number;
+    relationshipType?: string;
+    label?: string | null;
+    notes?: string;
+}): {
+    relationship: Relationship;
+    change: RelationshipChange | null;
+    previousValue: number;
+} | null;
+export declare function getRelationshipLabel(value: number): string;
+export declare function createBidirectionalRelationship(params: {
+    gameId: string;
+    entityA: {
+        id: string;
+        type: string;
+    };
+    entityB: {
+        id: string;
+        type: string;
+    };
+    relationshipType: string;
+    value?: number;
+    label?: string;
+    notes?: string;
+}): [Relationship, Relationship];

package/dist/tools/relationship.js

@@ -0,0 +1,324 @@
+import { v4 as uuidv4 } from "uuid";
+import { getDatabase, withTransaction } from "../db/connection.js";
+import { validateGameExists } from "./game.js";
+export function createRelationship(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 relationships (id, game_id, source_id, source_type, target_id, target_type, relationship_type, value, label, notes, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(id, params.gameId, params.sourceId, params.sourceType, params.targetId, params.targetType, params.relationshipType, params.value ?? 0, params.label || null, params.notes || "", now, now);
+    return {
+        id,
+        gameId: params.gameId,
+        sourceId: params.sourceId,
+        sourceType: params.sourceType,
+        targetId: params.targetId,
+        targetType: params.targetType,
+        relationshipType: params.relationshipType,
+        value: params.value ?? 0,
+        label: params.label || null,
+        notes: params.notes || "",
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+export function getRelationship(id) {
+    const db = getDatabase();
+    const row = db.prepare(`SELECT * FROM relationships WHERE id = ?`).get(id);
+    if (!row)
+        return null;
+    return {
+        id: row.id,
+        gameId: row.game_id,
+        sourceId: row.source_id,
+        sourceType: row.source_type,
+        targetId: row.target_id,
+        targetType: row.target_type,
+        relationshipType: row.relationship_type,
+        value: row.value,
+        label: row.label,
+        notes: row.notes,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+export function getRelationshipBetween(gameId, sourceId, targetId, relationshipType) {
+    const db = getDatabase();
+    let query = `SELECT * FROM relationships WHERE game_id = ? AND source_id = ? AND target_id = ?`;
+    const params = [gameId, sourceId, targetId];
+    if (relationshipType) {
+        query += ` AND relationship_type = ?`;
+        params.push(relationshipType);
+    }
+    query += ` LIMIT 1`;
+    const row = db.prepare(query).get(...params);
+    if (!row)
+        return null;
+    return {
+        id: row.id,
+        gameId: row.game_id,
+        sourceId: row.source_id,
+        sourceType: row.source_type,
+        targetId: row.target_id,
+        targetType: row.target_type,
+        relationshipType: row.relationship_type,
+        value: row.value,
+        label: row.label,
+        notes: row.notes,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+export function updateRelationship(id, updates) {
+    const db = getDatabase();
+    const current = getRelationship(id);
+    if (!current)
+        return null;
+    const now = new Date().toISOString();
+    const newType = updates.relationshipType ?? current.relationshipType;
+    const newValue = updates.value ?? current.value;
+    const newLabel = updates.label !== undefined ? updates.label : current.label;
+    const newNotes = updates.notes ?? current.notes;
+    db.prepare(`
+    UPDATE relationships
+    SET relationship_type = ?, value = ?, label = ?, notes = ?, updated_at = ?
+    WHERE id = ?
+  `).run(newType, newValue, newLabel, newNotes, now, id);
+    return {
+        ...current,
+        relationshipType: newType,
+        value: newValue,
+        label: newLabel,
+        notes: newNotes,
+        updatedAt: now,
+    };
+}
+function logRelationshipChange(relationshipId, previousValue, newValue, reason) {
+    const db = getDatabase();
+    const id = uuidv4();
+    const now = new Date().toISOString();
+    db.prepare(`
+    INSERT INTO relationship_history (id, relationship_id, previous_value, new_value, reason, timestamp)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(id, relationshipId, previousValue, newValue, reason, now);
+    return {
+        id,
+        relationshipId,
+        previousValue,
+        newValue,
+        reason,
+        timestamp: now,
+    };
+}
+export function modifyRelationship(params) {
+    const db = getDatabase();
+    const relationship = getRelationship(params.relationshipId);
+    if (!relationship)
+        return null;
+    // Validate bounds if both are provided
+    if (params.minValue !== undefined && params.maxValue !== undefined && params.minValue > params.maxValue) {
+        throw new Error(`Invalid bounds: minValue (${params.minValue}) cannot be greater than maxValue (${params.maxValue})`);
+    }
+    const previousValue = relationship.value;
+    let newValue = previousValue + params.delta;
+    // Apply bounds (clamp to min first, then max to ensure max takes precedence)
+    if (params.minValue !== undefined) {
+        newValue = Math.max(newValue, params.minValue);
+    }
+    if (params.maxValue !== undefined) {
+        newValue = Math.min(newValue, params.maxValue);
+    }
+    const now = new Date().toISOString();
+    // The value update and its history row must land together -- otherwise a
+    // failure between the two leaves a changed relationship value with no
+    // audit trail explaining why it changed.
+    const change = withTransaction(() => {
+        db.prepare(`UPDATE relationships SET value = ?, updated_at = ? WHERE id = ?`)
+            .run(newValue, now, params.relationshipId);
+        return logRelationshipChange(params.relationshipId, previousValue, newValue, params.reason || null);
+    });
+    return {
+        relationship: { ...relationship, value: newValue, updatedAt: now },
+        change,
+    };
+}
+export function deleteRelationship(id) {
+    const db = getDatabase();
+    const result = db.prepare(`DELETE FROM relationships WHERE id = ?`).run(id);
+    return result.changes > 0;
+}
+export function listRelationships(gameId, filter) {
+    const db = getDatabase();
+    let query = `SELECT * FROM relationships WHERE game_id = ?`;
+    const params = [gameId];
+    if (filter?.entityId) {
+        query += ` AND (source_id = ? OR target_id = ?)`;
+        params.push(filter.entityId, filter.entityId);
+    }
+    if (filter?.sourceId) {
+        query += ` AND source_id = ?`;
+        params.push(filter.sourceId);
+    }
+    if (filter?.targetId) {
+        query += ` AND target_id = ?`;
+        params.push(filter.targetId);
+    }
+    if (filter?.relationshipType) {
+        query += ` AND relationship_type = ?`;
+        params.push(filter.relationshipType);
+    }
+    if (filter?.entityType) {
+        query += ` AND (source_type = ? OR target_type = ?)`;
+        params.push(filter.entityType, filter.entityType);
+    }
+    query += ` ORDER BY updated_at DESC`;
+    const rows = db.prepare(query).all(...params);
+    return rows.map(row => ({
+        id: row.id,
+        gameId: row.game_id,
+        sourceId: row.source_id,
+        sourceType: row.source_type,
+        targetId: row.target_id,
+        targetType: row.target_type,
+        relationshipType: row.relationship_type,
+        value: row.value,
+        label: row.label,
+        notes: row.notes,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    }));
+}
+export function getRelationshipHistory(relationshipId, limit) {
+    const db = getDatabase();
+    let query = `SELECT * FROM relationship_history WHERE relationship_id = ? ORDER BY timestamp DESC`;
+    const params = [relationshipId];
+    if (limit) {
+        query += ` LIMIT ?`;
+        params.push(limit);
+    }
+    const rows = db.prepare(query).all(...params);
+    return rows.map(row => ({
+        id: row.id,
+        relationshipId: row.relationship_id,
+        previousValue: row.previous_value,
+        newValue: row.new_value,
+        reason: row.reason,
+        timestamp: row.timestamp,
+    }));
+}
+/**
+ * Update a relationship value with optional metadata changes. Supports both direct set and delta modes.
+ * Logs to history when value changes.
+ */
+export function updateRelationshipValue(params) {
+    const db = getDatabase();
+    const relationship = getRelationship(params.relationshipId);
+    if (!relationship)
+        return null;
+    // Validate bounds if both are provided
+    if (params.minValue !== undefined && params.maxValue !== undefined && params.minValue > params.maxValue) {
+        throw new Error(`Invalid bounds: minValue (${params.minValue}) cannot be greater than maxValue (${params.maxValue})`);
+    }
+    const previousValue = relationship.value;
+    let newValue;
+    if (params.mode === "delta") {
+        newValue = previousValue + params.value;
+    }
+    else {
+        newValue = params.value;
+    }
+    // Apply bounds (clamp to min first, then max to ensure max takes precedence)
+    if (params.minValue !== undefined) {
+        newValue = Math.max(newValue, params.minValue);
+    }
+    if (params.maxValue !== undefined) {
+        newValue = Math.min(newValue, params.maxValue);
+    }
+    const now = new Date().toISOString();
+    const newType = params.relationshipType ?? relationship.relationshipType;
+    const newLabel = params.label !== undefined ? params.label : relationship.label;
+    const newNotes = params.notes ?? relationship.notes;
+    // The value/metadata update and its (conditional) history row must land
+    // together, for the same reason as modifyRelationship() above.
+    const change = withTransaction(() => {
+        db.prepare(`
+      UPDATE relationships
+      SET relationship_type = ?, value = ?, label = ?, notes = ?, updated_at = ?
+      WHERE id = ?
+    `).run(newType, newValue, newLabel, newNotes, now, params.relationshipId);
+        // Log to history if value changed
+        if (newValue !== previousValue) {
+            return logRelationshipChange(params.relationshipId, previousValue, newValue, params.reason || null);
+        }
+        return null;
+    });
+    return {
+        relationship: {
+            ...relationship,
+            relationshipType: newType,
+            value: newValue,
+            label: newLabel,
+            notes: newNotes,
+            updatedAt: now,
+        },
+        change,
+        previousValue,
+    };
+}
+// Helper to get a value label based on thresholds
+export function getRelationshipLabel(value) {
+    if (value >= 80)
+        return "devoted";
+    if (value >= 60)
+        return "friendly";
+    if (value >= 40)
+        return "warm";
+    if (value >= 20)
+        return "cordial";
+    if (value >= 0)
+        return "neutral";
+    if (value >= -20)
+        return "cool";
+    if (value >= -40)
+        return "unfriendly";
+    if (value >= -60)
+        return "hostile";
+    if (value >= -80)
+        return "hateful";
+    return "nemesis";
+}
+// Create a bidirectional relationship (both directions with same initial value)
+export function createBidirectionalRelationship(params) {
+    // A "bidirectional" relationship is really two rows. If the second insert
+    // fails, we must not be left with a lopsided relationship where A knows
+    // about B but not vice versa -- so both inserts happen in one transaction.
+    return withTransaction(() => {
+        const relA = createRelationship({
+            gameId: params.gameId,
+            sourceId: params.entityA.id,
+            sourceType: params.entityA.type,
+            targetId: params.entityB.id,
+            targetType: params.entityB.type,
+            relationshipType: params.relationshipType,
+            value: params.value,
+            label: params.label,
+            notes: params.notes,
+        });
+        const relB = createRelationship({
+            gameId: params.gameId,
+            sourceId: params.entityB.id,
+            sourceType: params.entityB.type,
+            targetId: params.entityA.id,
+            targetType: params.entityA.type,
+            relationshipType: params.relationshipType,
+            value: params.value,
+            label: params.label,
+            notes: params.notes,
+        });
+        return [relA, relB];
+    });
+}

package/dist/tools/resource.d.ts

@@ -0,0 +1,93 @@
+import type { Resource, ResourceChange } from "../types/index.js";
+export declare function createResource(params: {
+    gameId: string;
+    ownerType: "game" | "character";
+    ownerId?: string;
+    name: string;
+    description?: string;
+    category?: string;
+    value?: number;
+    minValue?: number;
+    maxValue?: number;
+}): Resource;
+export declare function getResource(id: string): Resource | null;
+export declare function updateResource(id: string, updates: {
+    name?: string;
+    description?: string;
+    category?: string | null;
+    minValue?: number | null;
+    maxValue?: number | null;
+}): Resource | null;
+export declare function deleteResource(id: string): boolean;
+export declare function listResources(gameId: string, filter?: {
+    ownerType?: "game" | "character";
+    ownerId?: string;
+    category?: string;
+}): Resource[];
+/**
+ * Update a resource's value - either by delta or absolute set.
+ * Use mode: "delta" to add/subtract, mode: "set" to set an absolute value.
+ */
+export declare function updateResourceValue(params: {
+    resourceId: string;
+    mode: "delta" | "set";
+    value: number;
+    reason?: string;
+}): {
+    resource: Resource;
+    change: ResourceChange;
+} | null;
+/**
+ * Move `amount` from one resource to another, atomically. This is the ONLY
+ * write path for a resource that is a member of a declared 'conserved'
+ * constraint -- checkResourceConstraints() (constraint.ts) rejects
+ * update_resource_value against such a resource specifically because a
+ * single-resource write can't express where the counterpart delta comes
+ * from. This function is that counterpart-carrying write.
+ *
+ * WHY AN EXPLICIT TRANSFER TOOL, NOT A BALANCED MULTI-RESOURCE WRITE:
+ * A single-resource write against a conserved member is ambiguous -- the
+ * server has no way to infer where the offsetting delta should come from.
+ * Two designs resolve that ambiguity:
+ *   (a) an explicit transfer(from, to, amount) tool, or
+ *   (b) a "balanced write" tool taking an arbitrary { resourceId: delta }
+ *       map, rejecting the whole call unless every conserved set's deltas
+ *       sum to zero.
+ * (b) is more general -- it can reshuffle N members in one call -- but
+ * offloads real bookkeeping onto the caller: an LLM has to enumerate every
+ * affected resourceId, get every delta's sign right, and get the
+ * grouping-by-constraint-set right, all in one shot with no partial-progress
+ * checkpoint if it gets any of that wrong. (a) covers the overwhelming
+ * majority of real game actions directly ("trade 10 grain for gold", "the
+ * treasury pays the population") and composes: an N-member reshuffle is just
+ * several transfers, which the caller can still wrap in one withTransaction()
+ * if it needs to be all-or-nothing (see the "chains two transfers" tests in
+ * conserved.test.ts). That composability, plus the much smaller surface for
+ * a caller to get wrong, is why the narrower primitive was chosen.
+ *
+ * Scope is deliberately narrow: fromResourceId and toResourceId must already
+ * be members of the SAME declared 'conserved' constraint. This is not a
+ * general "move value between any two resources" tool -- for anything not
+ * under a 'conserved' constraint, update_resource_value remains the right
+ * tool (see checkResourceConstraints()). Keeping the two write paths
+ * mutually exclusive per resource means which one to use is never
+ * ambiguous.
+ *
+ * Never clamps. Clamping one side of a transfer would apply an uneven delta
+ * -- the source would lose less (or the destination gain less) than the
+ * other side moved by, silently creating or destroying value -- so any
+ * bound violation on either side rejects the whole transfer instead,
+ * regardless of whether a 'bounded' constraint is separately declared.
+ */
+export declare function transferResourceValue(params: {
+    fromResourceId: string;
+    toResourceId: string;
+    amount: number;
+    reason?: string;
+}): {
+    from: Resource;
+    to: Resource;
+    fromChange: ResourceChange;
+    toChange: ResourceChange;
+};
+export declare function getResourceHistory(resourceId: string, limit?: number): ResourceChange[];