bikky 0.3.3 → 0.3.6

package/dist/mcp/tools.js

@@ -6,7 +6,10 @@ import { z } from "zod";
 import { STALENESS_DAYS, THRESHOLD_DUPLICATE, THRESHOLD_RELATED, QDRANT_INDEXES, categoryValues, categoryEnumDescription, domainValues, domainEnumDescription, kindValues, kindEnumDescription, memorySubtypeValues, memorySubtypeEnumDescription, sourceValues, sourceEnumDescription, DEFAULT_CATEGORY, DEFAULT_DOMAIN, DEFAULT_KIND, DEFAULT_SOURCE, categoryForMemorySubtype, layerForMemorySubtype, normalizeCategory, normalizeDomain, normalizeKind, validateMemorySubtype, } from "./taxonomy.js";
 import { contentHash, daysSince, lastActivityDate, computeCombinedScore, buildFilter, formatFact, MEMORY_RECALL_EXCLUDED_KINDS, } from "./helpers.js";
 import { ready, qdrantUrl, qdrantApiKey, setupError, setQdrantUrl, setQdrantApiKey, setReady, getCollection, log, embed, getEmbeddingConfig, qdrantReq, ensureCollection, qdrantUpsert, qdrantSearch, qdrantScroll, qdrantSetPayload, qdrantGetPoints, } from "./api.js";
-import { saveConfig, loadConfig } from "../config.js";
+import { saveConfig, loadConfig, EXTRACTION_HEALTH_PATH } from "../config.js";
+import { existsSync, readFileSync } from "node:fs";
+import { inspectWatcherPaths, formatIssue } from "../daemon/watcher-health.js";
+import { addRedactionPayload, combineRedactions, redactStorageText, } from "../privacy/redaction.js";
 // ---------------------------------------------------------------------------
 // Runtime state
 // ---------------------------------------------------------------------------
@@ -22,15 +25,6 @@ function nowISO() {
 function newId() {
     return crypto.randomUUID();
 }
-function redactionOptions() {
-    return { enabled: false, redactPii: false };
-}
-function redactStorageText(text) {
-    return { text, redacted: false, summary: "none", matches: [] };
-}
-function combineRedactions(_items) {
-    return { redacted: false, summary: "none", matches: [] };
-}
 function resolveScope(workspaceId, includeLegacyWorkspace = false) {
     return {
         workspaceId: workspaceId?.trim() || undefined,
@@ -50,9 +44,6 @@ function addWorkspacePayload(payload, scope) {
     if (scope.actorId)
         payload["actor_id"] = scope.actorId;
 }
-function addRedactionPayload(_payload, _summary) {
-    // Task 243 keeps storage pass-through; redaction policy is out of scope for this branch.
-}
 async function getPointForWorkspaceWrite(factId, _scope) {
     const existing = await qdrantGetPoints([factId]);
     const point = existing.result?.[0];
@@ -199,6 +190,44 @@ export function registerTools(mcp) {
             status["embedding_connected"] = true;
         }
         catch { /* ignore */ }
+        // Watcher / extraction health (issue #58)
+        const warnings = [];
+        try {
+            const cfg = loadConfig();
+            status["watcher_path"] = cfg.watchers.copilot.path;
+            for (const issue of inspectWatcherPaths(cfg)) {
+                warnings.push(formatIssue(issue));
+            }
+        }
+        catch { /* ignore */ }
+        try {
+            if (existsSync(EXTRACTION_HEALTH_PATH)) {
+                const health = JSON.parse(readFileSync(EXTRACTION_HEALTH_PATH, "utf-8"));
+                status["extraction_last_tick_at"] = health.last_tick_at ?? null;
+                status["extraction_last_active_session_at"] = health.last_active_session_at ?? null;
+                status["extraction_active_session_count"] = health.active_session_count ?? 0;
+                if (health.last_active_session_at) {
+                    const hours = (Date.now() - Date.parse(health.last_active_session_at)) / 3_600_000;
+                    status["extraction_hours_since_active_session"] = Math.round(hours * 10) / 10;
+                    if (hours > 6) {
+                        warnings.push(`Watcher has not seen any active Copilot sessions for ${Math.round(hours)}h — ` +
+                            `check watcher_path (${health.watcher_path ?? "unknown"}) and that the daemon is running.`);
+                    }
+                }
+                else {
+                    status["extraction_hours_since_active_session"] = null;
+                    warnings.push("Daemon has never observed an active Copilot session — extraction may be stalled.");
+                }
+            }
+            else {
+                status["extraction_last_tick_at"] = null;
+                status["extraction_last_active_session_at"] = null;
+                status["extraction_hours_since_active_session"] = null;
+            }
+        }
+        catch { /* ignore */ }
+        if (warnings.length > 0)
+            status["warnings"] = warnings;
         if (!status["ready"] && missing.length > 0) {
             status["setup_instructions"] =
                 "Run `bikky setup` or guide the user. Pick one Qdrant option:\n" +
@@ -353,11 +382,17 @@ export function registerTools(mcp) {
             type: redactStorageText(relation.type),
             to: redactStorageText(relation.to),
         } : null;
-        const redactionSummary = combineRedactions([
+        const factRedactionSummary = combineRedactions([
             redactedContent,
             ...redactedEntities,
+        ]);
+        const relationRedactionSummary = combineRedactions([
             ...(redactedRelation ? [redactedRelation.from, redactedRelation.type, redactedRelation.to] : []),
         ]);
+        const redactionSummary = combineRedactions([
+            factRedactionSummary,
+            relationRedactionSummary,
+        ]);
         const hash = contentHash(normalizedCategory, redactedContent.text);
         const normalizedEntities = sanitizedEntities.map((e) => e.toLowerCase());
         const sanitizedRelation = redactedRelation ? {
@@ -509,7 +544,7 @@ export function registerTools(mcp) {
         if (review_status)
             payload["review_status"] = review_status;
         addWorkspacePayload(payload, scope);
-        addRedactionPayload(payload, redactionSummary);
+        addRedactionPayload(payload, factRedactionSummary);
         if (metadata && Object.keys(metadata).length > 0) {
             payload["metadata"] = metadata;
         }
@@ -541,7 +576,7 @@ export function registerTools(mcp) {
                 to_entity: sanitizedRelation.to.toLowerCase(),
             };
             addWorkspacePayload(relPayload, scope);
-            addRedactionPayload(relPayload, redactionSummary);
+            addRedactionPayload(relPayload, relationRedactionSummary);
             await qdrantUpsert(relationId, relVector, relPayload);
         }
         const result = {
@@ -669,6 +704,22 @@ export function registerTools(mcp) {
             return guard;
         const entityName = name.toLowerCase();
         const scope = resolveScope(workspace_id, include_legacy_workspace);
+        // Look up the daemon-classified entity type, if any.
+        let entityType = null;
+        try {
+            const typeFilter = scopedFilter(scope) ?? { must: [] };
+            typeFilter.must.push({ key: "kind", match: { value: "entity_type" } });
+            typeFilter.must.push({ key: "entity_name", match: { value: entityName } });
+            const typePoints = await qdrantScroll(typeFilter, 1);
+            const typePoint = typePoints.result?.points?.[0];
+            const payload = typePoint?.payload;
+            if (payload?.entity_type) {
+                entityType = String(payload.entity_type);
+            }
+        }
+        catch {
+            // Type lookup is best-effort — never fails the request.
+        }
         const factsFilter = scopedFilter(scope) ?? { must: [] };
         factsFilter.must.push({ key: "entities", match: { value: entityName } });
         const facts = await qdrantScroll(factsFilter, limit ?? 20);
@@ -681,13 +732,19 @@ export function registerTools(mcp) {
         const output = [];
         const factPoints = facts.result?.points ?? [];
         if (factPoints.length > 0) {
-            output.push(`## Facts about ${name} (${factPoints.length})`);
+            const header = entityType
+                ? `## Facts about ${name} [type: ${entityType}] (${factPoints.length})`
+                : `## Facts about ${name} (${factPoints.length})`;
+            output.push(header);
             for (const p of factPoints) {
                 if (p.payload.category !== "relation") {
                     output.push(`- ${formatFact(p)}`);
                 }
             }
         }
+        else if (entityType) {
+            output.push(`## ${name} [type: ${entityType}]`);
+        }
         const allRelations = [
             ...(relationsFrom.result?.points ?? []),
             ...(relationsTo.result?.points ?? []),
@@ -787,6 +844,13 @@ export function registerTools(mcp) {
                 superseded_by: `forgotten:${redactedReason.text}`,
                 superseded_at: now,
                 updated_at: now,
+                // Mark this fact's vector as a bad-exemplar centroid: future
+                // candidates with high cosine similarity will be auto-flagged
+                // for review. Forgotten facts keep their original vector — the
+                // is_bad_exemplar payload flag opts them into the centroid set
+                // without requiring a new point.
+                is_bad_exemplar: true,
+                bad_exemplar_reason: redactedReason.text,
             });
             return { content: [{ type: "text", text: JSON.stringify({
                             status: "forgotten",
@@ -843,6 +907,280 @@ export function registerTools(mcp) {
             return { content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : String(e)}` }] };
         }
     });
+    // ── memory_mark_useful ──────────────────────────────────────────────────
+    mcp.tool("memory_mark_useful", [
+        "Report that a previously recalled fact actually helped you answer the user's question or complete a task.",
+        "Bumps a 'useful_count' counter on the fact and writes a telemetry feedback_event row that future ranking work can aggregate.",
+        "Call this AFTER you used a fact from memory_recall / memory_entity and confirmed it was helpful — not for every recalled fact. If the fact was wrong or misleading, use memory_report_outcome with outcome='wrong' or 'misleading' instead.",
+    ].join(" "), {
+        fact_id: z.string().describe("ID of the fact that was useful (from memory_recall or memory_entity)."),
+        note: z.string().optional().describe("Optional short note about how the fact was useful (e.g. 'unblocked auth debug'). Stored on the telemetry event for future analysis."),
+        workspace_id: z.string().optional().describe("Workspace namespace. Omit to use the default from config."),
+    }, async ({ fact_id, note, workspace_id }) => {
+        const guard = requireReady();
+        if (guard)
+            return guard;
+        const now = nowISO();
+        try {
+            const scope = resolveScope(workspace_id);
+            const writable = await getPointForWorkspaceWrite(fact_id, scope);
+            if (writable.error) {
+                return { content: [{ type: "text", text: JSON.stringify(writable.error, null, 2) }], isError: true };
+            }
+            const existingPt = writable.point;
+            const currentCount = existingPt?.payload.useful_count ?? 0;
+            const newCount = currentCount + 1;
+            await qdrantSetPayload([fact_id], {
+                useful_count: newCount,
+                last_useful_at: now,
+                updated_at: now,
+            });
+            // Write a telemetry feedback_event row so the signal is also visible
+            // to aggregations and review tooling.
+            const eventId = newId();
+            const eventContent = note
+                ? `Fact ${fact_id} marked useful: ${note}`
+                : `Fact ${fact_id} marked useful.`;
+            const redactedEvent = redactStorageText(eventContent);
+            const eventPayload = {
+                content: redactedEvent.text,
+                category: "observations",
+                domain: "software_engineering",
+                kind: "telemetry",
+                memory_subtype: "feedback_event",
+                layer: "memory_object",
+                entities: [],
+                source: "agent",
+                confidence: 1.0,
+                importance: 0.3,
+                content_hash: contentHash("feedback_event", `${fact_id}:useful:${now}`),
+                target_fact_id: fact_id,
+                feedback_kind: "useful",
+                created_at: now,
+                updated_at: now,
+            };
+            addWorkspacePayload(eventPayload, scope);
+            addRedactionPayload(eventPayload, redactedEvent);
+            try {
+                const eventVector = await embed(redactedEvent.text);
+                await qdrantUpsert(eventId, eventVector, eventPayload);
+            }
+            catch (e) {
+                log("WARN", `Failed to record feedback_event: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify({
+                            status: "marked_useful",
+                            fact_id,
+                            useful_count: newCount,
+                            event_id: eventId,
+                        }) }],
+            };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : String(e)}` }] };
+        }
+    });
+    // ── memory_report_outcome ───────────────────────────────────────────────
+    mcp.tool("memory_report_outcome", [
+        "Report the downstream outcome of using a recalled fact — useful, misleading, irrelevant, or wrong.",
+        "Writes a telemetry outcome_event row that future ranking and review work can aggregate. Unlike memory_mark_useful (positive-only, bumps a counter), this records a richer signal including negative outcomes and optional notes.",
+        "Use this when you can confidently judge whether a fact actually helped: 'useful' = helped you complete the task; 'misleading' = pointed in a wrong direction; 'irrelevant' = matched semantically but didn't help; 'wrong' = factually incorrect (also consider memory_forget for clearly wrong facts).",
+    ].join(" "), {
+        fact_id: z.string().describe("ID of the fact whose outcome you are reporting."),
+        outcome: z.enum(["useful", "misleading", "irrelevant", "wrong"]).describe("How the fact actually played out. 'useful' = helped you finish the task; 'misleading' = sent you the wrong way; 'irrelevant' = semantically matched but didn't help; 'wrong' = factually incorrect."),
+        notes: z.string().optional().describe("Optional short context for the outcome (e.g. 'API moved in v2', 'wrong port number'). Stored on the telemetry event for future analysis."),
+        workspace_id: z.string().optional().describe("Workspace namespace. Omit to use the default from config."),
+    }, async ({ fact_id, outcome, notes, workspace_id }) => {
+        const guard = requireReady();
+        if (guard)
+            return guard;
+        const now = nowISO();
+        try {
+            const scope = resolveScope(workspace_id);
+            const target = await getPointForWorkspaceWrite(fact_id, scope);
+            if (target.error) {
+                return { content: [{ type: "text", text: JSON.stringify(target.error, null, 2) }], isError: true };
+            }
+            const eventId = newId();
+            const eventContent = notes
+                ? `Fact ${fact_id} outcome=${outcome}: ${notes}`
+                : `Fact ${fact_id} outcome=${outcome}.`;
+            const redactedEvent = redactStorageText(eventContent);
+            const eventPayload = {
+                content: redactedEvent.text,
+                category: "observations",
+                domain: "software_engineering",
+                kind: "telemetry",
+                memory_subtype: "outcome_event",
+                layer: "memory_object",
+                entities: [],
+                source: "agent",
+                confidence: 1.0,
+                importance: outcome === "wrong" || outcome === "misleading" ? 0.6 : 0.3,
+                content_hash: contentHash("outcome_event", `${fact_id}:${outcome}:${now}`),
+                target_fact_id: fact_id,
+                outcome,
+                created_at: now,
+                updated_at: now,
+            };
+            addWorkspacePayload(eventPayload, scope);
+            addRedactionPayload(eventPayload, redactedEvent);
+            const eventVector = await embed(redactedEvent.text);
+            await qdrantUpsert(eventId, eventVector, eventPayload);
+            return {
+                content: [{ type: "text", text: JSON.stringify({
+                            status: "outcome_recorded",
+                            fact_id,
+                            outcome,
+                            event_id: eventId,
+                        }) }],
+            };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : String(e)}` }] };
+        }
+    });
+    // ── memory_session_summary ──────────────────────────────────────────────
+    mcp.tool("memory_session_summary", [
+        "Persist a compact summary of the current session — what got done, what decisions were made, what's still open.",
+        "Stored as kind='summary', memory_subtype='session_index', source='agent'. Keep it short (target 30-80 words). Future sessions retrieve these via memory_recall to bootstrap context faster than re-reading the original transcript.",
+        "Call this near session close (or at major milestone boundaries) when the work is meaningful enough to want a future agent to inherit. Skip for trivial single-question sessions.",
+    ].join(" "), {
+        content: z.string().describe("The summary text. Atomic, self-contained, 30-80 words ideally. Should answer: what was the goal, what did we do, what remains?"),
+        entities: z.array(z.string()).optional().describe("Lowercase entity names mentioned by the summary (services, repos, people, concepts). Used for entity-scoped recall later."),
+        episode_id: z.string().optional().describe("Coherent activity-segment ID for grouping with related captures."),
+        workstream_key: z.string().optional().describe("Durable continuity key for a long-running objective (survives across sessions)."),
+        task_key: z.string().optional().describe("Task or issue key (e.g. GitHub issue number, JIRA key)."),
+        repo: z.string().optional().describe("Repository or project surface this summary relates to."),
+        workspace_id: z.string().optional().describe("Workspace namespace. Omit to use the default from config."),
+    }, async ({ content, entities, episode_id, workstream_key, task_key, repo, workspace_id }) => {
+        const guard = requireReady();
+        if (guard)
+            return guard;
+        lastStoreTime = Date.now();
+        const now = nowISO();
+        try {
+            const scope = resolveScope(workspace_id);
+            const normalizedEntities = (entities ?? []).map((e) => e.trim().toLowerCase()).filter(Boolean);
+            const summaryId = newId();
+            const redactedContent = redactStorageText(content);
+            const vector = await embed(redactedContent.text);
+            const payload = {
+                content: redactedContent.text,
+                category: categoryForMemorySubtype("session_index") ?? "projects",
+                domain: "software_engineering",
+                kind: "summary",
+                memory_subtype: "session_index",
+                layer: layerForMemorySubtype("session_index") ?? "episode",
+                entities: normalizedEntities,
+                source: "agent",
+                confidence: 0.9,
+                importance: 0.6,
+                content_hash: contentHash("summary", redactedContent.text),
+                reinforcement_count: 1,
+                last_reinforced_at: now,
+                superseded_by: null,
+                superseded_at: null,
+                created_at: now,
+                updated_at: now,
+            };
+            if (episode_id)
+                payload["episode_id"] = episode_id;
+            if (workstream_key)
+                payload["workstream_key"] = workstream_key;
+            if (task_key)
+                payload["task_key"] = task_key;
+            if (repo)
+                payload["repo"] = repo;
+            addWorkspacePayload(payload, scope);
+            addRedactionPayload(payload, redactedContent);
+            await qdrantUpsert(summaryId, vector, payload);
+            return {
+                content: [{ type: "text", text: JSON.stringify({
+                            status: "summary_stored",
+                            summary_id: summaryId,
+                            workspace_id: scope.workspaceId,
+                        }) }],
+            };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : String(e)}` }] };
+        }
+    });
+    // ── memory_distill ──────────────────────────────────────────────────────
+    mcp.tool("memory_distill", [
+        "Persist a distilled convention — a reusable learning, pattern, or runbook synthesized from multiple prior memories.",
+        "Stored as kind='distilled', memory_subtype='convention', source='agent'. Use this when you've noticed a pattern across several prior facts/sessions that's worth surfacing as its own atomic learning. The new memory will rank above raw facts in semantic recall because distilled patterns are higher-signal.",
+        "Provide 'supersedes' if this distillation replaces an earlier convention. The original stays in storage but is excluded from recall.",
+    ].join(" "), {
+        content: z.string().describe("One-sentence reusable convention or pattern. Should be self-contained and applicable beyond a single situation."),
+        entities: z.array(z.string()).describe("Lowercase entity names this distillation applies to (services, tools, concepts)."),
+        supersedes: z.string().optional().describe("ID of an earlier distilled fact that this one replaces. Old fact is marked superseded and excluded from recall."),
+        task_key: z.string().optional().describe("Task or issue key associated with this learning, if relevant."),
+        repo: z.string().optional().describe("Repository or project surface this learning applies to."),
+        workspace_id: z.string().optional().describe("Workspace namespace. Omit to use the default from config."),
+    }, async ({ content, entities, supersedes, task_key, repo, workspace_id }) => {
+        const guard = requireReady();
+        if (guard)
+            return guard;
+        lastStoreTime = Date.now();
+        const now = nowISO();
+        try {
+            const scope = resolveScope(workspace_id);
+            const normalizedEntities = entities.map((e) => e.trim().toLowerCase()).filter(Boolean);
+            const distilledId = newId();
+            const redactedContent = redactStorageText(content);
+            const vector = await embed(redactedContent.text);
+            if (supersedes) {
+                const existing = await getPointForWorkspaceWrite(supersedes, scope);
+                if (existing.error) {
+                    return { content: [{ type: "text", text: JSON.stringify(existing.error, null, 2) }], isError: true };
+                }
+                await qdrantSetPayload([supersedes], {
+                    superseded_by: distilledId,
+                    superseded_at: now,
+                });
+            }
+            const payload = {
+                content: redactedContent.text,
+                category: categoryForMemorySubtype("convention") ?? "observations",
+                domain: "software_engineering",
+                kind: "distilled",
+                memory_subtype: "convention",
+                layer: layerForMemorySubtype("convention") ?? "domain",
+                entities: normalizedEntities,
+                source: "agent",
+                confidence: 0.9,
+                importance: 0.7,
+                content_hash: contentHash("distilled", redactedContent.text),
+                reinforcement_count: 1,
+                last_reinforced_at: now,
+                superseded_by: null,
+                superseded_at: null,
+                created_at: now,
+                updated_at: now,
+            };
+            if (task_key)
+                payload["task_key"] = task_key;
+            if (repo)
+                payload["repo"] = repo;
+            addWorkspacePayload(payload, scope);
+            addRedactionPayload(payload, redactedContent);
+            await qdrantUpsert(distilledId, vector, payload);
+            return {
+                content: [{ type: "text", text: JSON.stringify({
+                            status: "distilled_stored",
+                            distilled_id: distilledId,
+                            supersedes: supersedes ?? null,
+                            workspace_id: scope.workspaceId,
+                        }) }],
+            };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : String(e)}` }] };
+        }
+    });
     // ── memory_review ───────────────────────────────────────────────────────
     mcp.tool("memory_review", [
         "Triage facts that were extracted automatically by the bikky daemon (source='daemon').",