@massa-ai/core 1.2.1

package/dist/tools/compact_snapshot.js

@@ -0,0 +1,139 @@
+/**
+ * Compact Snapshot Tool
+ *
+ * MCP tool for building a reference-based compaction snapshot of the current
+ * session's observations. The snapshot is a bounded (<~2KB) table-of-contents
+ * with runnable search/recall calls — NOT inlined data. Zero information loss:
+ * raw events stay in the observation store; the snapshot just points to them.
+ *
+ * SESSION continuity, NOT task state. This is distinct from `create_checkpoint`
+ * (which versions TASK progress/decisions/files in PostgreSQL memories table). See
+ * `packages/core/src/services/SESSION-STATE.md` for the full reconciliation.
+ *
+ * Optionally persists the snapshot itself as an observation of category
+ * `compaction-snapshots` so it is available for future sessions.
+ */
+import { logger } from "@massa-ai/shared";
+import { getObservationStore, newObservationId, } from "../data/memory/observation-repository.js";
+import { getCompactionSnapshotService } from "../services/hooks/compaction-snapshot-service.js";
+import { getAttributionResolver, } from "../services/hooks/attribution-resolver.js";
+export class CompactSnapshotTool {
+    name = "compact_snapshot";
+    storeOverride;
+    resolverOverride;
+    constructor(options = {}) {
+        this.storeOverride = options.store;
+        this.resolverOverride = options.resolver;
+    }
+    description = "Build a reference-based compaction snapshot — bounded table-of-contents with " +
+        "runnable search/recall calls for the current session's observations (SESSION " +
+        "continuity, not task state). Zero information loss — raw events stay in the " +
+        "observation store; the snapshot points to them. Distinct from checkpoints " +
+        "(which version TASK progress in PostgreSQL memories table). Optionally persists the snapshot " +
+        "as an observation of category 'compaction-snapshots' in PostgreSQL observations table.";
+    inputSchema = {
+        type: "object",
+        properties: {
+            sessionId: {
+                type: "string",
+                description: "Session ID to build the snapshot for",
+            },
+            projectId: {
+                type: "string",
+                description: "Project ID (defaults to 'default')",
+            },
+            persist: {
+                type: "boolean",
+                default: false,
+                description: "If true, persist the snapshot as an observation of category 'compaction-snapshots'",
+            },
+            cwd: {
+                type: "string",
+                description: "Optional working directory of the session (used for attribution containment when the caller projectId is not a registered workspace)",
+            },
+        },
+        required: ["sessionId"],
+    };
+    async handle(params) {
+        const { sessionId, projectId = "default", persist = false, cwd } = params;
+        if (!sessionId || typeof sessionId !== "string") {
+            return { success: false, error: "sessionId is required" };
+        }
+        try {
+            const store = this.storeOverride ?? getObservationStore();
+            const service = getCompactionSnapshotService(store);
+            const snapshot = service.build({
+                sessionId,
+                projectId,
+                compactCount: 0,
+            });
+            // Optionally persist the snapshot as an observation so it survives across
+            // sessions and can be retrieved by future compaction cycles.
+            let persistedId;
+            if (persist && snapshot.eventCount > 0) {
+                persistedId = newObservationId();
+                try {
+                    const attribution = await (this.resolverOverride ?? getAttributionResolver()).resolve({ callerProjectId: projectId, sessionId, cwd });
+                    store.insert({
+                        id: persistedId,
+                        projectId: attribution.projectId,
+                        sessionId,
+                        source: "pre-compact",
+                        category: "compaction-snapshots",
+                        payloadJson: JSON.stringify({
+                            snapshot: snapshot.xml,
+                            eventCount: snapshot.eventCount,
+                            compactCount: snapshot.compactCount,
+                            generatedAt: snapshot.generatedAt,
+                            sectionCount: snapshot.sections.length,
+                        }),
+                        importance: 0.8,
+                        createdAt: Date.now(),
+                        attributionSource: attribution.source,
+                    });
+                    // Mirror HookService: admission (insert) survived → record sticky pin.
+                    (this.resolverOverride ?? getAttributionResolver()).pinSession(sessionId, attribution.projectId, attribution.source);
+                    logger.info("compact_snapshot: persisted", {
+                        persistedId,
+                        sessionId,
+                        bytes: snapshot.bytes,
+                    });
+                }
+                catch (e) {
+                    logger.warn("compact_snapshot: persist failed (non-fatal)", {
+                        error: e.message,
+                    });
+                    persistedId = undefined;
+                }
+            }
+            return {
+                success: true,
+                data: {
+                    snapshot: snapshot.xml,
+                    bytes: snapshot.bytes,
+                    eventCount: snapshot.eventCount,
+                    sectionCount: snapshot.sections.length,
+                    sections: snapshot.sections.map((s) => ({
+                        category: s.category,
+                        label: s.label,
+                        count: s.count,
+                        observationIds: s.observationIds,
+                    })),
+                    persistedId,
+                    generatedAt: snapshot.generatedAt,
+                },
+                metadata: {
+                    tokensSaved: Math.round(snapshot.bytes / 4),
+                },
+            };
+        }
+        catch (error) {
+            logger.error("compact_snapshot: failed", error, { sessionId });
+            return {
+                success: false,
+                error: `Failed to build compaction snapshot: ${error.message}`,
+            };
+        }
+    }
+}
+//# sourceMappingURL=compact_snapshot.js.map

package/dist/tools/compact_snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compact_snapshot.js","sourceRoot":"","sources":["../../src/tools/compact_snapshot.ts"],"names":[],"mappings":"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"}

package/dist/tools/compress_context.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Compress Context Tool
+ *
+ * Comprime contexto usando compressão semântica com LLM.
+ * Mantém estrutura essencial, remove detalhes, economiza tokens.
+ */
+import { IToolHandler } from "@massa-ai/shared";
+import { ToolResponse } from "@massa-ai/shared";
+export declare class CompressContextTool implements IToolHandler {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            content: {
+                type: string;
+                description: string;
+            };
+            strategy: {
+                type: string;
+                enum: string[];
+                description: string;
+                default: string;
+            };
+            language: {
+                type: string;
+                description: string;
+            };
+            targetRatio: {
+                type: string;
+                description: string;
+                default: number;
+            };
+        };
+        required: string[];
+    };
+    private compressor;
+    constructor();
+    handle(params: unknown): Promise<ToolResponse>;
+}
+//# sourceMappingURL=compress_context.d.ts.map

package/dist/tools/compress_context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compress_context.d.ts","sourceRoot":"","sources":["../../src/tools/compress_context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAiBhD,qBAAa,mBAAoB,YAAW,YAAY;IACtD,IAAI,SAAsB;IAC1B,WAAW,SACwE;IACnF,WAAW;;;;;;;;;;;;;;;;;;;;;;;;MA8BT;IAEF,OAAO,CAAC,UAAU,CAAiB;;IAM7B,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;CAsErD"}

package/dist/tools/compress_context.js

@@ -0,0 +1,103 @@
+/**
+ * Compress Context Tool
+ *
+ * Comprime contexto usando compressão semântica com LLM.
+ * Mantém estrutura essencial, remove detalhes, economiza tokens.
+ */
+import { CodeCompressor } from "../services/compression/code-compressor.js";
+import { logger } from "@massa-ai/shared";
+import { estimateTokens } from "@massa-ai/shared";
+import { validateEnum } from "./enum-validation.js";
+export class CompressContextTool {
+    name = "compress_context";
+    description = "Compress context using semantic compression (keeps structure, removes details)";
+    inputSchema = {
+        type: "object",
+        properties: {
+            content: {
+                type: "string",
+                description: "Content to compress",
+            },
+            strategy: {
+                type: "string",
+                enum: [
+                    "code_structure",
+                    "conversation_summary",
+                    "semantic_dedup",
+                    "hierarchical",
+                ],
+                description: "Compression strategy",
+                default: "code_structure",
+            },
+            language: {
+                type: "string",
+                description: "Programming language (for code compression)",
+            },
+            targetRatio: {
+                type: "number",
+                description: "Target compression ratio (0-1, e.g., 0.7 = 70% reduction)",
+                default: 0.7,
+            },
+        },
+        required: ["content"],
+    };
+    compressor;
+    constructor() {
+        this.compressor = new CodeCompressor();
+    }
+    async handle(params) {
+        const { content, language, targetRatio = 0.7, } = params;
+        const strategy = validateEnum("strategy", params.strategy ?? "code_structure", [
+            "code_structure",
+            "conversation_summary",
+            "semantic_dedup",
+            "hierarchical",
+        ]);
+        try {
+            const originalTokens = estimateTokens(content, language || "code");
+            logger.info("Compressing context", {
+                originalTokens,
+                strategy,
+                targetRatio,
+            });
+            // Perform compression
+            const result = await this.compressor.compress(content, strategy);
+            const compressedTokens = estimateTokens(result.compressed, language || "code");
+            const actualRatio = 1 - compressedTokens / originalTokens;
+            const tokensSaved = originalTokens - compressedTokens;
+            logger.info("Context compressed", {
+                originalTokens,
+                compressedTokens,
+                tokensSaved,
+                actualRatio: actualRatio.toFixed(2),
+                targetRatio,
+            });
+            return {
+                success: true,
+                data: {
+                    compressed: result.compressed,
+                    originalLength: content.length,
+                    compressedLength: result.compressed.length,
+                    originalTokens,
+                    compressedTokens,
+                    strategy,
+                },
+                metadata: {
+                    tokensSaved,
+                    compressionRatio: actualRatio,
+                },
+            };
+        }
+        catch (error) {
+            logger.error("Failed to compress context", error, {
+                strategy,
+                contentLength: content.length,
+            });
+            return {
+                success: false,
+                error: `Failed to compress context: ${error.message}`,
+            };
+        }
+    }
+}
+//# sourceMappingURL=compress_context.js.map

package/dist/tools/compress_context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compress_context.js","sourceRoot":"","sources":["../../src/tools/compress_context.ts"],"names":[],"mappings":"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"}

package/dist/tools/create_checkpoint.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Create Checkpoint Tool
+ *
+ * MCP tool for creating task checkpoints (manual or milestone).
+ * Thin layer — delegates to CheckpointManager service.
+ */
+import { IToolHandler, ToolResponse } from "@massa-ai/shared";
+export declare class CreateCheckpointTool implements IToolHandler {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            taskId: {
+                type: string;
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+            status: {
+                type: string;
+                enum: string[];
+                description: string;
+                default: string;
+            };
+            currentStep: {
+                type: string;
+                description: string;
+            };
+            progressPercent: {
+                type: string;
+                description: string;
+                default: number;
+            };
+            totalSteps: {
+                type: string;
+                description: string;
+                default: number;
+            };
+            completedSteps: {
+                type: string;
+                description: string;
+                default: number;
+            };
+            checkpointType: {
+                type: string;
+                enum: string[];
+                description: string;
+                default: string;
+            };
+            agentId: {
+                type: string;
+                description: string;
+            };
+            projectId: {
+                type: string;
+                description: string;
+            };
+            memoryIds: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            fileChanges: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            decisions: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            learnings: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            nextAction: {
+                type: string;
+                description: string;
+            };
+            pendingValidations: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            format: {
+                type: string;
+                enum: string[];
+                description: string;
+                default: string;
+            };
+            fields: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    private checkpointManager;
+    constructor();
+    handle(params: unknown): Promise<ToolResponse>;
+}
+//# sourceMappingURL=create_checkpoint.d.ts.map

package/dist/tools/create_checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create_checkpoint.d.ts","sourceRoot":"","sources":["../../src/tools/create_checkpoint.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAyC,MAAM,kBAAkB,CAAC;AAwCrG,qBAAa,oBAAqB,YAAW,YAAY;IACvD,IAAI,SAAuB;IAC3B,WAAW,SAI6C;IACxD,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA6FT;IAEF,OAAO,CAAC,iBAAiB,CAAoB;;IAMvC,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;CAmGrD"}

package/dist/tools/create_checkpoint.js

@@ -0,0 +1,184 @@
+/**
+ * Create Checkpoint Tool
+ *
+ * MCP tool for creating task checkpoints (manual or milestone).
+ * Thin layer — delegates to CheckpointManager service.
+ */
+import { TaskStatus, CheckpointType } from "@massa-ai/shared";
+import { logger } from "@massa-ai/shared";
+import { CheckpointManager } from "../services/checkpoint/checkpoint-manager.js";
+import { serializeToolResponse } from "./serialize.js";
+import { validateEnum } from "./enum-validation.js";
+export class CreateCheckpointTool {
+    name = "create_checkpoint";
+    description = "Create a checkpoint to save current task progress — versioned TASK state " +
+        "(progress, decisions, files modified) for resumption or rollback. " +
+        "Distinct from compact_snapshot, which preserves SESSION continuity across /compact. " +
+        "Useful for long-running tasks to enable resumption.";
+    inputSchema = {
+        type: "object",
+        properties: {
+            taskId: {
+                type: "string",
+                description: "Unique identifier for the task being checkpointed",
+            },
+            description: {
+                type: "string",
+                description: "Human-readable description of the task",
+            },
+            status: {
+                type: "string",
+                enum: ["pending", "in_progress", "completed", "failed", "paused"],
+                description: "Current task status",
+                default: "in_progress",
+            },
+            currentStep: {
+                type: "string",
+                description: "Name of the current step being worked on",
+            },
+            progressPercent: {
+                type: "number",
+                description: "Overall progress percentage (0-100)",
+                default: 0,
+            },
+            totalSteps: {
+                type: "number",
+                description: "Total number of steps in the task",
+                default: 0,
+            },
+            completedSteps: {
+                type: "number",
+                description: "Number of steps completed so far",
+                default: 0,
+            },
+            checkpointType: {
+                type: "string",
+                enum: ["manual", "milestone"],
+                description: "Type of checkpoint (milestone checkpoints have longer TTL)",
+                default: "manual",
+            },
+            agentId: {
+                type: "string",
+                description: "Agent creating the checkpoint",
+            },
+            projectId: {
+                type: "string",
+                description: "Project ID",
+            },
+            memoryIds: {
+                type: "array",
+                items: { type: "string" },
+                description: "Memory IDs related to this task",
+            },
+            fileChanges: {
+                type: "array",
+                items: { type: "string" },
+                description: "File paths modified during this task",
+            },
+            decisions: {
+                type: "array",
+                items: { type: "string" },
+                description: "Memory IDs of decisions made",
+            },
+            learnings: {
+                type: "array",
+                items: { type: "string" },
+                description: "Key learnings or insights from the task",
+            },
+            nextAction: {
+                type: "string",
+                description: "The next action to take when restoring this checkpoint",
+            },
+            pendingValidations: {
+                type: "array",
+                items: { type: "string" },
+                description: "Validations still pending",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "toon"],
+                description: "Output format",
+                default: "toon",
+            },
+            fields: {
+                type: "array",
+                items: { type: "string" },
+                description: "Projection — keep only these keys (dotted paths supported, e.g. ['nodes.symbol']). Absent/empty → full data.",
+            },
+        },
+        required: ["taskId", "description"],
+    };
+    checkpointManager;
+    constructor() {
+        this.checkpointManager = CheckpointManager.getInstance();
+    }
+    async handle(params) {
+        const { taskId, description, currentStep = "", progressPercent = 0, totalSteps = 0, completedSteps = 0, agentId, projectId, memoryIds = [], fileChanges = [], decisions = [], learnings = [], nextAction, pendingValidations = [], format = "toon", fields, } = params;
+        const status = validateEnum("status", params.status ?? TaskStatus.IN_PROGRESS, [
+            TaskStatus.PENDING,
+            TaskStatus.IN_PROGRESS,
+            TaskStatus.COMPLETED,
+            TaskStatus.FAILED,
+            TaskStatus.PAUSED,
+        ]);
+        const checkpointType = validateEnum("checkpointType", params.checkpointType ?? "manual", ["manual", "milestone"]);
+        try {
+            const state = {
+                taskId,
+                description,
+                status: status,
+                progress: {
+                    total: totalSteps,
+                    completed: completedSteps,
+                    currentStep,
+                    percentage: progressPercent,
+                },
+                context: {
+                    decisions,
+                    filesRead: [],
+                    filesModified: fileChanges,
+                    errors: [],
+                    learnings,
+                },
+                agentState: {
+                    lastAction: currentStep || "checkpoint created",
+                    nextAction,
+                    pendingValidations,
+                },
+                startedAt: Date.now(),
+                lastCheckpointAt: Date.now(),
+                checkpointCount: 0,
+            };
+            const checkpoint = this.checkpointManager.createCheckpoint(state, {
+                agentId,
+                projectId,
+                checkpointType: checkpointType === "milestone"
+                    ? CheckpointType.MILESTONE
+                    : CheckpointType.MANUAL,
+                memoryIds,
+                fileChanges,
+            });
+            logger.info("Checkpoint tool: created", {
+                checkpointId: checkpoint.id,
+                taskId,
+                type: checkpointType,
+            });
+            const responseData = {
+                checkpointId: checkpoint.id,
+                taskId,
+                type: checkpointType,
+                createdAt: checkpoint.createdAt,
+                expiresAt: checkpoint.expiresAt,
+            };
+            return serializeToolResponse(responseData, { format, fields });
+        }
+        catch (error) {
+            logger.error("Failed to create checkpoint", error, { taskId });
+            return {
+                success: false,
+                error: `Failed to create checkpoint: ${error.message}`,
+            };
+        }
+    }
+}
+//# sourceMappingURL=create_checkpoint.js.map

package/dist/tools/create_checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create_checkpoint.js","sourceRoot":"","sources":["../../src/tools/create_checkpoint.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAyC,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACrG,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAoCpD,MAAM,OAAO,oBAAoB;IAC/B,IAAI,GAAG,mBAAmB,CAAC;IAC3B,WAAW,GACT,2EAA2E;QAC3E,oEAAoE;QACpE,sFAAsF;QACtF,qDAAqD,CAAC;IACxD,WAAW,GAAG;QACZ,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,mDAAmD;aACjE;YACD,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,wCAAwC;aACtD;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,SAAS,EAAE,aAAa,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC;gBACjE,WAAW,EAAE,qBAAqB;gBAClC,OAAO,EAAE,aAAa;aACvB;YACD,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,0CAA0C;aACxD;YACD,eAAe,EAAE;gBACf,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,qCAAqC;gBAClD,OAAO,EAAE,CAAC;aACX;YACD,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,mCAAmC;gBAChD,OAAO,EAAE,CAAC;aACX;YACD,cAAc,EAAE;gBACd,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,kCAAkC;gBAC/C,OAAO,EAAE,CAAC;aACX;YACD,cAAc,EAAE;gBACd,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC;gBAC7B,WAAW,EAAE,4DAA4D;gBACzE,OAAO,EAAE,QAAQ;aAClB;YACD,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,+BAA+B;aAC7C;YACD,SAAS,EAAE;gBACT,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,YAAY;aAC1B;YACD,SAAS,EAAE;gBACT,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EAAE,iCAAiC;aAC/C;YACD,WAAW,EAAE;gBACX,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EAAE,sCAAsC;aACpD;YACD,SAAS,EAAE;gBACT,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EAAE,8BAA8B;aAC5C;YACD,SAAS,EAAE;gBACT,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EAAE,yCAAyC;aACvD;YACD,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,wDAAwD;aACtE;YACD,kBAAkB,EAAE;gBAClB,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EAAE,2BAA2B;aACzC;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;gBACtB,WAAW,EAAE,eAAe;gBAC5B,OAAO,EAAE,MAAM;aAChB;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EACT,8GAA8G;aACjH;SACF;QACD,QAAQ,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC;KACpC,CAAC;IAEM,iBAAiB,CAAoB;IAE7C;QACE,IAAI,CAAC,iBAAiB,GAAG,iBAAiB,CAAC,WAAW,EAAE,CAAC;IAC3D,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAe;QAC1B,MAAM,EACJ,MAAM,EACN,WAAW,EACX,WAAW,GAAG,EAAE,EAChB,eAAe,GAAG,CAAC,EACnB,UAAU,GAAG,CAAC,EACd,cAAc,GAAG,CAAC,EAClB,OAAO,EACP,SAAS,EACT,SAAS,GAAG,EAAE,EACd,WAAW,GAAG,EAAE,EAChB,SAAS,GAAG,EAAE,EACd,SAAS,GAAG,EAAE,EACd,UAAU,EACV,kBAAkB,GAAG,EAAE,EACvB,MAAM,GAAG,MAAM,EACf,MAAM,GACP,GAAG,MAAgC,CAAC;QAErC,MAAM,MAAM,GAAG,YAAY,CACzB,QAAQ,EACP,MAAiC,CAAC,MAAM,IAAI,UAAU,CAAC,WAAW,EACnE;YACE,UAAU,CAAC,OAAO;YAClB,UAAU,CAAC,WAAW;YACtB,UAAU,CAAC,SAAS;YACpB,UAAU,CAAC,MAAM;YACjB,UAAU,CAAC,MAAM;SACO,CAC3B,CAAC;QACF,MAAM,cAAc,GAAG,YAAY,CACjC,gBAAgB,EACf,MAAiC,CAAC,cAAc,IAAI,QAAQ,EAC7D,CAAC,QAAQ,EAAE,WAAW,CAAU,CACjC,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,KAAK,GAAc;gBACvB,MAAM;gBACN,WAAW;gBACX,MAAM,EAAE,MAAoB;gBAC5B,QAAQ,EAAE;oBACR,KAAK,EAAE,UAAU;oBACjB,SAAS,EAAE,cAAc;oBACzB,WAAW;oBACX,UAAU,EAAE,eAAe;iBAC5B;gBACD,OAAO,EAAE;oBACP,SAAS;oBACT,SAAS,EAAE,EAAE;oBACb,aAAa,EAAE,WAAW;oBAC1B,MAAM,EAAE,EAAE;oBACV,SAAS;iBACV;gBACD,UAAU,EAAE;oBACV,UAAU,EAAE,WAAW,IAAI,oBAAoB;oBAC/C,UAAU;oBACV,kBAAkB;iBACnB;gBACD,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;gBACrB,gBAAgB,EAAE,IAAI,CAAC,GAAG,EAAE;gBAC5B,eAAe,EAAE,CAAC;aACnB,CAAC;YAEF,MAAM,UAAU,GAAG,IAAI,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,KAAK,EAAE;gBAChE,OAAO;gBACP,SAAS;gBACT,cAAc,EACZ,cAAc,KAAK,WAAW;oBAC5B,CAAC,CAAC,cAAc,CAAC,SAAS;oBAC1B,CAAC,CAAC,cAAc,CAAC,MAAM;gBAC3B,SAAS;gBACT,WAAW;aACZ,CAAC,CAAC;YAEH,MAAM,CAAC,IAAI,CAAC,0BAA0B,EAAE;gBACtC,YAAY,EAAE,UAAU,CAAC,EAAE;gBAC3B,MAAM;gBACN,IAAI,EAAE,cAAc;aACrB,CAAC,CAAC;YAEH,MAAM,YAAY,GAAG;gBACnB,YAAY,EAAE,UAAU,CAAC,EAAE;gBAC3B,MAAM;gBACN,IAAI,EAAE,cAAc;gBACpB,SAAS,EAAE,UAAU,CAAC,SAAS;gBAC/B,SAAS,EAAE,UAAU,CAAC,SAAS;aAChC,CAAC;YAEF,OAAO,qBAAqB,CAAC,YAAY,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QACjE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,6BAA6B,EAAE,KAAc,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;YACxE,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,gCAAiC,KAAe,CAAC,OAAO,EAAE;aAClE,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/dist/tools/delete_memory.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Delete Memory Tool
+ *
+ * Thin MCP tool layer — delegates to MemoryController.
+ * Hard-deletes the memory and severs its graph edges. Soft-delete is a
+ * Phase 1 concern (needs a deleted_at column + recall filtering).
+ */
+import { IToolHandler, ToolResponse } from "@massa-ai/shared";
+export declare class DeleteMemoryTool implements IToolHandler {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            id: {
+                type: string;
+                description: string;
+            };
+            format: {
+                type: string;
+                enum: string[];
+                description: string;
+                default: string;
+            };
+            fields: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    private controller;
+    constructor();
+    handle(params: unknown): Promise<ToolResponse>;
+}
+//# sourceMappingURL=delete_memory.d.ts.map

package/dist/tools/delete_memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delete_memory.d.ts","sourceRoot":"","sources":["../../src/tools/delete_memory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAW9D,qBAAa,gBAAiB,YAAW,YAAY;IACnD,IAAI,SAAmB;IACvB,WAAW,SAC4D;IACvE,WAAW;;;;;;;;;;;;;;;;;;;;;;MAkBT;IAEF,OAAO,CAAC,UAAU,CAAmB;;IAM/B,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;CAerD"}