gsd-pi 2.75.0-dev.2203010a0 → 2.75.0-dev.96d4bb599

package/dist/resources/extensions/gsd/tools/memory-tools.js

@@ -0,0 +1,306 @@
+// GSD Memory Tools — Phase 1 executors for capture_thought, memory_query, gsd_graph
+//
+// These executors back the three memory-layer tools the LLM can call at any
+// point in a session. They build on the existing `memory-store.ts` layer
+// (SQLite memories table) and degrade gracefully when the DB is unavailable.
+//
+// Phase 1 scope:
+//   - capture_thought → create a memory with the caller-supplied category/content
+//   - memory_query    → keyword-filtered, score-ranked listing of active memories
+//   - gsd_graph       → returns a memory and its supersedes edges only (Phase 4 adds memory_relations)
+import { _getAdapter, isDbAvailable } from "../gsd-db.js";
+import { createMemory, getActiveMemoriesRanked, queryMemoriesRanked, reinforceMemory, } from "../memory-store.js";
+import { traverseGraph } from "../memory-relations.js";
+function dbUnavailable(operation) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: "Error: GSD database is not available. Memory tools require an initialized .gsd/ project.",
+            },
+        ],
+        details: { operation, error: "db_unavailable" },
+        isError: true,
+    };
+}
+const VALID_CATEGORIES = new Set([
+    "architecture",
+    "convention",
+    "gotcha",
+    "preference",
+    "environment",
+    "pattern",
+]);
+export function executeMemoryCapture(params) {
+    if (!isDbAvailable())
+        return dbUnavailable("memory_capture");
+    const category = (params.category ?? "").trim().toLowerCase();
+    const content = (params.content ?? "").trim();
+    if (!category || !content) {
+        return {
+            content: [{ type: "text", text: "Error: category and content are required." }],
+            details: { operation: "memory_capture", error: "missing_fields" },
+            isError: true,
+        };
+    }
+    if (!VALID_CATEGORIES.has(category)) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: invalid category "${category}". Must be one of: ${[...VALID_CATEGORIES].join(", ")}.`,
+                },
+            ],
+            details: { operation: "memory_capture", error: "invalid_category" },
+            isError: true,
+        };
+    }
+    const confidence = clampConfidence(params.confidence);
+    const scope = normalizeScope(params.scope);
+    const tags = normalizeTags(params.tags);
+    const id = createMemory({ category, content, confidence, scope, tags });
+    if (!id) {
+        return {
+            content: [{ type: "text", text: "Error: failed to create memory." }],
+            details: { operation: "memory_capture", error: "create_failed" },
+            isError: true,
+        };
+    }
+    return {
+        content: [{ type: "text", text: `Captured ${id} (${category}): ${content}` }],
+        details: { operation: "memory_capture", id, category, confidence, scope, tags },
+    };
+}
+function normalizeScope(value) {
+    if (typeof value !== "string")
+        return "project";
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? "project" : trimmed;
+}
+function normalizeTags(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((t) => typeof t === "string" && t.trim().length > 0).slice(0, 10);
+}
+function clampConfidence(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return 0.8;
+    if (value < 0.1)
+        return 0.1;
+    if (value > 0.99)
+        return 0.99;
+    return value;
+}
+export function executeMemoryQuery(params) {
+    if (!isDbAvailable())
+        return dbUnavailable("memory_query");
+    const query = (params.query ?? "").trim();
+    const k = clampTopK(params.k, 10);
+    const includeSuperseded = params.include_superseded === true;
+    const category = params.category?.trim().toLowerCase() || undefined;
+    const scopeFilter = params.scope?.trim() || undefined;
+    const tagFilter = params.tag?.trim().toLowerCase() || undefined;
+    try {
+        let ranked = [];
+        if (query) {
+            ranked = queryMemoriesRanked({
+                query,
+                k,
+                category,
+                scope: scopeFilter,
+                tag: tagFilter,
+                include_superseded: includeSuperseded,
+            });
+        }
+        else {
+            const candidates = includeSuperseded
+                ? includeSupersededMemories(getActiveMemoriesRanked(200))
+                : getActiveMemoriesRanked(200);
+            ranked = candidates
+                .filter((m) => {
+                if (category && m.category.toLowerCase() !== category)
+                    return false;
+                if (scopeFilter && m.scope !== scopeFilter)
+                    return false;
+                if (tagFilter && !m.tags.map((t) => t.toLowerCase()).includes(tagFilter))
+                    return false;
+                return true;
+            })
+                .slice(0, k)
+                .map((memory) => ({
+                memory,
+                score: memory.confidence * (1 + memory.hit_count * 0.1),
+                keywordRank: null,
+                semanticRank: null,
+                confidenceBoost: memory.confidence * (1 + memory.hit_count * 0.1),
+                reason: "ranked",
+            }));
+        }
+        const hits = ranked.map((r) => ({
+            id: r.memory.id,
+            category: r.memory.category,
+            content: r.memory.content,
+            confidence: r.memory.confidence,
+            hit_count: r.memory.hit_count,
+            score: r.score,
+            reason: r.reason,
+            keyword_rank: r.keywordRank,
+            semantic_rank: r.semanticRank,
+        }));
+        if (params.reinforce_hits) {
+            for (const h of hits)
+                reinforceMemory(h.id);
+        }
+        const summary = hits.length === 0
+            ? "No matching memories."
+            : hits.map((h) => `- [${h.id}] (${h.category}) ${h.content}`).join("\n");
+        return {
+            content: [{ type: "text", text: summary }],
+            details: {
+                operation: "memory_query",
+                query,
+                k,
+                returned: hits.length,
+                hits,
+            },
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Error: memory query failed: ${err.message}` }],
+            details: { operation: "memory_query", error: err.message },
+            isError: true,
+        };
+    }
+}
+function clampTopK(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return fallback;
+    if (value < 1)
+        return 1;
+    if (value > 50)
+        return 50;
+    return Math.floor(value);
+}
+function includeSupersededMemories(rankedActive) {
+    const adapter = _getAdapter();
+    if (!adapter)
+        return rankedActive;
+    try {
+        const rows = adapter.prepare("SELECT * FROM memories").all();
+        return rows.map((row) => {
+            let tags = [];
+            if (typeof row["tags"] === "string") {
+                try {
+                    const parsed = JSON.parse(row["tags"]);
+                    if (Array.isArray(parsed))
+                        tags = parsed.filter((t) => typeof t === "string");
+                }
+                catch {
+                    /* leave empty */
+                }
+            }
+            return {
+                seq: row["seq"],
+                id: row["id"],
+                category: row["category"],
+                content: row["content"],
+                confidence: row["confidence"],
+                source_unit_type: row["source_unit_type"] ?? null,
+                source_unit_id: row["source_unit_id"] ?? null,
+                created_at: row["created_at"],
+                updated_at: row["updated_at"],
+                superseded_by: row["superseded_by"] ?? null,
+                hit_count: row["hit_count"],
+                scope: row["scope"] ?? "project",
+                tags,
+            };
+        });
+    }
+    catch {
+        return rankedActive;
+    }
+}
+export function executeGsdGraph(params) {
+    if (!isDbAvailable())
+        return dbUnavailable("gsd_graph");
+    if (params.mode === "build") {
+        // The extractor emits LINK actions incrementally (Phase 4). There is no
+        // batch rebuild step to run today — ingest artifacts via `/gsd memory
+        // extract <SRC-...>` and the next extraction turn will add edges.
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "gsd_graph build acknowledged. Graph edges are populated incrementally by memory " +
+                        "extraction (including LINK actions). Use `/gsd memory extract <SRC-...>` to trigger " +
+                        "extraction against a specific ingested source.",
+                },
+            ],
+            details: { operation: "gsd_graph", mode: "build", built: 0 },
+        };
+    }
+    if (params.mode !== "query") {
+        return {
+            content: [{ type: "text", text: `Error: unknown mode "${params.mode}". Must be "build" or "query".` }],
+            details: { operation: "gsd_graph", error: "invalid_mode" },
+            isError: true,
+        };
+    }
+    const memoryId = params.memoryId?.trim();
+    if (!memoryId) {
+        return {
+            content: [{ type: "text", text: "Error: memoryId is required for mode=query." }],
+            details: { operation: "gsd_graph", error: "missing_memory_id" },
+            isError: true,
+        };
+    }
+    try {
+        const graph = traverseGraph(memoryId, clampDepth(params.depth));
+        const rel = params.rel?.trim().toLowerCase() || null;
+        const edges = rel ? graph.edges.filter((e) => e.rel === rel) : graph.edges;
+        const relevantIds = new Set([memoryId]);
+        for (const e of edges) {
+            relevantIds.add(e.from);
+            relevantIds.add(e.to);
+        }
+        const nodes = graph.nodes.filter((n) => relevantIds.has(n.id));
+        if (nodes.length === 0) {
+            return {
+                content: [{ type: "text", text: `No memory found with id ${memoryId}.` }],
+                details: { operation: "gsd_graph", mode: "query", memoryId, nodes: [], edges: [] },
+            };
+        }
+        const summary = [
+            `Memory ${memoryId} — ${nodes.length} node(s), ${edges.length} edge(s).`,
+            ...nodes.map((n) => `  [${n.id}] (${n.category}) ${n.content}`),
+            ...edges.map((e) => `  ${e.from} --${e.rel}-> ${e.to}`),
+        ].join("\n");
+        return {
+            content: [{ type: "text", text: summary }],
+            details: {
+                operation: "gsd_graph",
+                mode: "query",
+                memoryId,
+                nodes: nodes.map((n) => ({ id: n.id, category: n.category, content: n.content })),
+                edges: edges.map((e) => ({ from: e.from, to: e.to, rel: e.rel })),
+            },
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Error: graph query failed: ${err.message}` }],
+            details: { operation: "gsd_graph", error: err.message },
+            isError: true,
+        };
+    }
+}
+function clampDepth(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return 1;
+    if (value < 0)
+        return 0;
+    if (value > 5)
+        return 5;
+    return Math.floor(value);
+}

package/dist/resources/extensions/gsd/tools/skip-slice.js

@@ -0,0 +1,78 @@
+/**
+ * skip-slice handler — the core operation behind gsd_skip_slice.
+ *
+ * Marks a slice as skipped and cascades the skip to every non-closed task in
+ * that slice. Without the task cascade the deep-check in
+ * executeCompleteMilestone reports pending tasks inside the skipped slice and
+ * blocks milestone completion (see #4375).
+ *
+ * This function performs DB writes only. The MCP wrapper in
+ * bootstrap/db-tools.ts handles state-cache invalidation and STATE.md rebuild.
+ */
+import { getSlice, getSliceTasks, isDbAvailable, transaction, updateSliceStatus, updateTaskStatus, } from "../gsd-db.js";
+import { isClosedStatus } from "../status-guards.js";
+/**
+ * Mark a slice as "skipped" and cascade the skip to every non-closed task in
+ * that slice. Runs as a single transaction so slice status and task statuses
+ * are always consistent.
+ *
+ * Behaviour summary:
+ * - Unknown slice → returns {@link SkipSliceResult} with `error`.
+ * - Slice already complete/done → returns `error` (cannot un-complete).
+ * - Slice already skipped → still cascades leftover non-closed tasks
+ *   (heals inconsistent historical state from projects that ran older
+ *   versions before the #4375 cascade fix).
+ * - Tasks in closed status (complete/done/skipped) are never downgraded.
+ */
+export function handleSkipSlice(params) {
+    const base = {
+        milestoneId: params.milestoneId,
+        sliceId: params.sliceId,
+        tasksSkipped: 0,
+        wasAlreadySkipped: false,
+        reason: params.reason,
+    };
+    // Fail loudly on a closed DB so a `null` from getSlice() inside the
+    // transaction unambiguously means "slice not found", never "DB unavailable".
+    // The MCP wrapper in bootstrap/db-tools.ts runs ensureDbOpen() before calling
+    // this helper; this guard protects direct callers (tests, future code).
+    if (!isDbAvailable()) {
+        throw new Error("handleSkipSlice: GSD database is not available");
+    }
+    // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ────
+    let guardError = null;
+    let guardCode = null;
+    let wasAlreadySkipped = false;
+    let tasksSkipped = 0;
+    transaction(() => {
+        const slice = getSlice(params.milestoneId, params.sliceId);
+        if (!slice) {
+            guardError = `Slice ${params.sliceId} not found in milestone ${params.milestoneId}`;
+            guardCode = "slice_not_found";
+            return;
+        }
+        if (slice.status === "complete" || slice.status === "done") {
+            guardError = `Slice ${params.sliceId} is already complete — cannot skip.`;
+            guardCode = "already_complete";
+            return;
+        }
+        wasAlreadySkipped = slice.status === "skipped";
+        if (!wasAlreadySkipped) {
+            updateSliceStatus(params.milestoneId, params.sliceId, "skipped");
+        }
+        // Cascade: mark every non-closed task as skipped so milestone completion
+        // doesn't trip the deep-task guard (#4375). Closed tasks (complete/done/
+        // skipped) are left untouched — we never downgrade.
+        const tasks = getSliceTasks(params.milestoneId, params.sliceId);
+        for (const task of tasks) {
+            if (!isClosedStatus(task.status)) {
+                updateTaskStatus(params.milestoneId, params.sliceId, task.id, "skipped");
+                tasksSkipped++;
+            }
+        }
+    });
+    if (guardError) {
+        return { ...base, error: guardError, errorCode: guardCode ?? undefined };
+    }
+    return { ...base, tasksSkipped, wasAlreadySkipped };
+}