@devflow-tools/mcp-server 0.17.0 → 0.17.2

package/dist/tools.js

@@ -6,6 +6,7 @@ import { normalizeTurnId, openGlobalDevFlowDatabase, } from "@devflow-tools/data
 import { createHash } from "node:crypto";
 import { isAbsolute, normalize, relative } from "node:path";
 import { normalizeMemoryCandidates, OBSERVATION_TYPE_SCHEMA, rejectedToolResult, TOOL_RESULT_OUTPUT_SCHEMA, } from "./tool-contracts.js";
+import { emitSemanticControlLog } from '@devflow-tools/telemetry';
 export const GUARDED_CORE_TOOL_NAMES = new Set([
     "get_project_context",
     "search_symbol",
@@ -205,7 +206,7 @@ export function getCoreTools(knowledgeScopes = []) {
         },
         {
             name: "memory_commit_turn",
-            description: "提交当前用户轮次并返回 DevFlow canonical receipt。显式记忆 turn 会从 durable prompt 自动恢复并提交；普通 turn 必须提供宿主语义判断得到的 candidates。",
+            description: "提交当前用户轮次并返回 DevFlow canonical receipt。显式记忆先可靠直存，再用带逐字 evidenceSpans 的宿主 candidates 幂等精炼；普通 turn 必须提供宿主语义判断得到的 candidates。",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -213,7 +214,7 @@ export function getCoreTools(knowledgeScopes = []) {
                     candidates: {
                         type: "array",
                         minItems: 1,
-                        description: "普通 turn 必填；显式记忆 turn 可省略，服务会使用已持久化的显式内容。",
+                        description: "普通 turn 必填；显式记忆恢复时可省略，已有 canonical receipt 的显式 turn 则用它执行证据绑定语义精炼。",
                         items: {
                             type: "object",
                             properties: {
@@ -224,6 +225,11 @@ export function getCoreTools(knowledgeScopes = []) {
                                 concepts: { type: "array", items: { type: "string" } },
                                 importance: { type: "number", minimum: 1, maximum: 10 },
                                 confidence: { type: "number", minimum: 0, maximum: 1 },
+                                disposition: {
+                                    type: "string",
+                                    enum: ["durable_memory", "turn_constraint"],
+                                    description: "Classify reusable project truth separately from instructions that apply only to the current turn. Defaults to durable_memory for compatibility.",
+                                },
                                 subject: { type: "string", minLength: 1, description: "Concrete project facet or entity the durable fact concerns" },
                                 predicate: { type: "string", minLength: 1, description: "Stable relation such as use, require, prefer, version, or state" },
                                 value: { type: "string", minLength: 1, description: "Exact selected value; preserve package names, flags, versions, and identifiers" },
@@ -247,8 +253,14 @@ export function getCoreTools(knowledgeScopes = []) {
                                     items: { type: "string" },
                                     description: "Session event IDs that directly support this memory. Omit only when committing the current single turn event.",
                                 },
+                                evidenceSpans: {
+                                    type: "array",
+                                    minItems: 1,
+                                    maxItems: 16,
+                                    items: { type: "string", minLength: 1 },
+                                    description: "Exact, verbatim substrings copied from the canonical user prompt that support this candidate. Required when refining an already committed explicit-memory turn.",
+                                },
                             },
-                            required: ["type", "title"],
                         },
                     },
                 },
@@ -411,7 +423,7 @@ function replayMemoryDecision(turn) {
         replayed: true,
     };
 }
-function resolveMemoryDecisionTurn(database, projectRoot, sessionId, requestedTurnId) {
+function resolveMemoryDecisionTurn(database, projectRoot, sessionId, requestedTurnId, options = {}) {
     if (typeof requestedTurnId === 'string' && requestedTurnId.trim()) {
         let normalized;
         try {
@@ -437,6 +449,7 @@ function resolveMemoryDecisionTurn(database, projectRoot, sessionId, requestedTu
             };
         }
         return requested.status === 'pending'
+            || (options.allowCommittedExplicitRefinement && requested.status === 'committed' && requested.source === 'explicit_intent')
             ? { turn: requested }
             : { replay: replayMemoryDecision(requested) };
     }
@@ -547,6 +560,92 @@ function findHostAction(actions, stepId) {
     const matches = actions.filter(action => action.stepId === stepId);
     return matches.length === 1 ? matches[0] : null;
 }
+function resolveBoundContextTask(input) {
+    if (!input.intentArtifactHash) {
+        return {
+            query: input.agentQuery,
+            expandedTerms: input.expandedTerms,
+            requestId: input.requestId,
+            turnId: input.turnId,
+        };
+    }
+    if (!input.sessionId || !input.turnId || !input.requestId) {
+        throw new Error('TASK_IDENTITY_INCOMPLETE:intent artifact binding requires session, turn, and request');
+    }
+    const database = openGlobalDevFlowDatabase(undefined, { busyTimeoutMs: 250 });
+    try {
+        const record = database.getTaskIntentArtifact(input.intentArtifactHash);
+        if (!record)
+            throw new Error(`TASK_INTENT_NOT_FOUND:${input.intentArtifactHash}`);
+        if (record.projectRoot !== input.projectRoot || record.sessionId !== input.sessionId
+            || record.turnId !== input.turnId || record.requestId !== input.requestId) {
+            throw new Error('TASK_IDENTITY_MISMATCH:intent artifact does not belong to this MCP request');
+        }
+        const planRecord = database.getChannelQueryPlanForIntent({
+            projectRoot: record.projectRoot,
+            sessionId: record.sessionId,
+            turnId: record.turnId,
+            sourceIntentHash: record.artifactHash,
+        });
+        if (!planRecord)
+            throw new Error(`QUERY_PLAN_NOT_FOUND:${record.artifactHash}`);
+        const identity = {
+            projectRoot: record.projectRoot,
+            projectId: record.projectId,
+            hostId: record.hostId,
+            sessionId: record.sessionId,
+            turnId: record.turnId,
+            requestId: record.requestId,
+            ...(record.executionId ? { executionId: record.executionId } : {}),
+        };
+        const artifact = {
+            identity,
+            version: record.version,
+            ...(record.supersedesHash ? { supersedesHash: record.supersedesHash } : {}),
+            rawPrompt: record.rawPrompt,
+            normalizedPrompt: record.normalizedPrompt,
+            ...(record.command ? { command: record.command } : {}),
+            slashArgs: record.slashArgs,
+            ...(record.activeSkill ? { activeSkill: record.activeSkill } : {}),
+            intent: record.intent,
+            action: record.action,
+            entities: record.entities,
+            targetAnchors: record.targetAnchors,
+            policyConstraints: record.policyConstraints,
+            classificationEvidence: record.classificationEvidence,
+            sourceEventIds: record.sourceEventIds,
+            sourceHash: record.sourceHash,
+            artifactHash: record.artifactHash,
+            createdAt: record.createdAt,
+        };
+        const queryPlan = {
+            identity,
+            sourceIntentHash: planRecord.sourceIntentHash,
+            planHash: planRecord.planHash,
+            code: planRecord.code,
+            memory: planRecord.memory,
+            knowledge: planRecord.knowledge,
+            generatedBy: planRecord.generatedBy,
+            ...(planRecord.degradation ? { degradation: planRecord.degradation } : {}),
+            createdAt: planRecord.createdAt,
+        };
+        const query = stripArtifactCommand(artifact.normalizedPrompt, artifact.command);
+        const expandedTerms = [input.agentQuery, input.expandedTerms]
+            .filter((value) => typeof value === 'string' && value.trim().length > 0)
+            .join(' ')
+            .slice(0, 4_000) || undefined;
+        return { query, expandedTerms, requestId: record.requestId, turnId: record.turnId, intentArtifact: artifact, queryPlan };
+    }
+    finally {
+        database.close();
+    }
+}
+function stripArtifactCommand(prompt, command) {
+    if (!command)
+        return prompt;
+    const escaped = command.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+    return prompt.replace(new RegExp(`^\\/${escaped}\\b`, 'iu'), '').trim() || prompt;
+}
 export function createToolHandlers(engines, boundProjectRoot) {
     const hasBoundProjectRoot = typeof boundProjectRoot === 'string' && boundProjectRoot.trim().length > 0;
     const canonicalProjectRoot = canonicalizeProjectRoot(String(boundProjectRoot ?? process.cwd()));
@@ -560,23 +659,37 @@ export function createToolHandlers(engines, boundProjectRoot) {
         }
     }
     const handlers = {
-        get_project_context: async ({ query, mode, expandedTerms, retrievalSessionId, baselineReceipt, missingContext, _devflow_session_id, _devflow_execution_id, _devflow_request_id, _devflow_active_skill, activeSkill }) => getProjectContextResult(engines.context, {
-            query: query,
-            mode: mode ?? "fast",
-            expandedTerms: typeof expandedTerms === "string" ? expandedTerms : undefined,
-            retrievalSessionId: typeof retrievalSessionId === 'string' ? retrievalSessionId : undefined,
-            baselineReceipt: typeof baselineReceipt === 'string' ? baselineReceipt : undefined,
-            missingContext: Array.isArray(missingContext) ? missingContext : undefined,
-            sessionId: typeof _devflow_session_id === 'string' ? _devflow_session_id : process.env.DEVFLOW_SESSION_ID ?? undefined,
-            executionId: typeof _devflow_execution_id === 'string' ? _devflow_execution_id : undefined,
-            requestId: typeof _devflow_request_id === 'string' ? _devflow_request_id : undefined,
-            activeSkill: typeof _devflow_active_skill === 'string'
-                ? _devflow_active_skill
-                : typeof activeSkill === 'string' ? activeSkill : undefined,
-            projectRoot: boundProjectRoot,
-            host: 'claude-code',
-            command: 'devflow:context',
-        }, getFreshnessMs()),
+        get_project_context: async ({ query, mode, expandedTerms, retrievalSessionId, baselineReceipt, missingContext, _devflow_session_id, _devflow_execution_id, _devflow_request_id, _devflow_turn_id, _devflow_intent_artifact_hash, _devflow_active_skill, activeSkill }) => {
+            const boundTask = resolveBoundContextTask({
+                projectRoot: canonicalProjectRoot,
+                sessionId: typeof _devflow_session_id === 'string' ? _devflow_session_id : undefined,
+                requestId: typeof _devflow_request_id === 'string' ? _devflow_request_id : undefined,
+                turnId: typeof _devflow_turn_id === 'string' ? _devflow_turn_id : undefined,
+                intentArtifactHash: typeof _devflow_intent_artifact_hash === 'string' ? _devflow_intent_artifact_hash : undefined,
+                agentQuery: query,
+                expandedTerms: typeof expandedTerms === 'string' ? expandedTerms : undefined,
+            });
+            return getProjectContextResult(engines.context, {
+                query: boundTask.query,
+                mode: mode ?? "fast",
+                expandedTerms: boundTask.expandedTerms,
+                retrievalSessionId: typeof retrievalSessionId === 'string' ? retrievalSessionId : undefined,
+                baselineReceipt: typeof baselineReceipt === 'string' ? baselineReceipt : undefined,
+                missingContext: Array.isArray(missingContext) ? missingContext : undefined,
+                sessionId: typeof _devflow_session_id === 'string' ? _devflow_session_id : process.env.DEVFLOW_SESSION_ID ?? undefined,
+                executionId: typeof _devflow_execution_id === 'string' ? _devflow_execution_id : undefined,
+                requestId: boundTask.requestId,
+                turnId: boundTask.turnId,
+                intentArtifact: boundTask.intentArtifact,
+                queryPlan: boundTask.queryPlan,
+                activeSkill: boundTask.intentArtifact?.activeSkill ?? (typeof _devflow_active_skill === 'string'
+                    ? _devflow_active_skill
+                    : typeof activeSkill === 'string' ? activeSkill : undefined),
+                projectRoot: boundProjectRoot,
+                host: 'claude-code',
+                command: boundTask.intentArtifact?.command ?? 'devflow:context',
+            }, getFreshnessMs());
+        },
         search_symbol: async ({ symbol }) => {
             const result = await engines.indexer.findSymbol(symbol);
             return {
@@ -987,18 +1100,22 @@ export function createToolHandlers(engines, boundProjectRoot) {
             }
             const database = openGlobalDevFlowDatabase();
             try {
-                const resolution = resolveMemoryDecisionTurn(database, String(projectRoot), sessionId, turnId);
+                const resolution = resolveMemoryDecisionTurn(database, String(projectRoot), sessionId, turnId, {
+                    allowCommittedExplicitRefinement: Array.isArray(candidates) && candidates.length > 0,
+                });
                 if (resolution.replay)
                     return resolution.replay;
                 if (resolution.error || !resolution.turn)
                     return { ...resolution.error, committed: false };
                 const pending = resolution.turn;
+                const explicitRefinement = pending.status === 'committed' && pending.source === 'explicit_intent';
                 const recovery = getMemoryTurnRecoveryPayload(database, pending);
                 const memory = engines.memory;
-                if (recovery?.operation === 'commit_explicit' && recovery.explicitContent?.trim()) {
+                if (pending.status === 'pending' && recovery?.operation === 'commit_explicit' && recovery.explicitContent?.trim()) {
                     await ensureMemoryTurnEvent(memory, pending, recovery);
                     const saved = await memory.saveExplicitMemoryIntent(recovery.explicitContent.trim(), sessionId, pending.eventId);
-                    const receipt = commitMemoryReceipt(database, pending, [saved.id], 'explicit_intent', 'explicit_user_request_mcp_recovery');
+                    const recoveredMemoryIds = [...new Set([saved.id, ...(saved.relatedMemoryIds ?? [])])];
+                    const receipt = commitMemoryReceipt(database, pending, recoveredMemoryIds, 'explicit_intent', 'explicit_user_request_mcp_recovery');
                     if (memory.finalizeTurnDecision && receipt.receiptId) {
                         try {
                             await memory.finalizeTurnDecision({
@@ -1007,7 +1124,7 @@ export function createToolHandlers(engines, boundProjectRoot) {
                                 turnId: pending.turnId,
                                 receiptId: receipt.receiptId,
                                 status: 'committed',
-                                memoryIds: [saved.id],
+                                memoryIds: recoveredMemoryIds,
                                 reason: 'explicit_user_request_mcp_recovery',
                             });
                         }
@@ -1029,15 +1146,17 @@ export function createToolHandlers(engines, boundProjectRoot) {
                             });
                         }
                     }
-                    database.enqueueWork({
-                        idempotencyKey: `vector:${String(projectRoot)}:${saved.id}`,
-                        kind: 'memory.vector_backfill',
-                        projectRoot: String(projectRoot),
-                        sessionId,
-                        turnId: pending.turnId,
-                        payload: { observationId: saved.id },
-                        maxAttempts: 20,
-                    });
+                    for (const memoryId of recoveredMemoryIds) {
+                        database.enqueueWork({
+                            idempotencyKey: `vector:${String(projectRoot)}:${memoryId}`,
+                            kind: 'memory.vector_backfill',
+                            projectRoot: String(projectRoot),
+                            sessionId,
+                            turnId: pending.turnId,
+                            payload: { observationId: memoryId },
+                            maxAttempts: 20,
+                        });
+                    }
                     return acceptedMemoryReceipt(receipt, {
                         acceptedCandidates: [],
                         rejectedCandidates: [],
@@ -1056,6 +1175,19 @@ export function createToolHandlers(engines, boundProjectRoot) {
                             accepted: 0, rejected: validation.rejected,
                         },
                     });
+                    if (explicitRefinement) {
+                        return {
+                            ...replayMemoryDecision(pending),
+                            status: 'degraded',
+                            replayed: false,
+                            refined: false,
+                            degradation: {
+                                reason: 'invalid_host_refinement_candidates',
+                                fallback: 'deterministic_explicit_memory',
+                            },
+                            rejectedCandidates: validation.rejected,
+                        };
+                    }
                     return {
                         ...rejectedToolResult('INVALID_MEMORY_CANDIDATES', 'No valid durable memory candidates were supplied.', false, validation.rejected.flatMap(candidate => candidate.fieldErrors)),
                         committed: false,
@@ -1077,11 +1209,124 @@ export function createToolHandlers(engines, boundProjectRoot) {
                     entities: candidate.entities,
                     temporal: candidate.temporal,
                     sourceEventIds: candidate.sourceEventIds,
+                    evidenceSpans: candidate.evidenceSpans,
+                    disposition: candidate.disposition,
                 }));
                 await ensureMemoryTurnEvent(memory, pending, recovery);
+                if (explicitRefinement) {
+                    if (!memory.refineExplicitTurnObservations) {
+                        return {
+                            ...replayMemoryDecision(pending),
+                            status: 'degraded',
+                            replayed: false,
+                            degradation: {
+                                reason: 'explicit_refinement_unavailable',
+                                fallback: 'deterministic_explicit_memory',
+                            },
+                        };
+                    }
+                    try {
+                        const refined = await memory.refineExplicitTurnObservations(pending.eventId, sessionId, parsed);
+                        const refinedMemoryIds = refined.memories.map(item => item.id);
+                        const refinementReceiptId = `memory-receipt:${createHash('sha256')
+                            .update(`${pending.turnId}\0host_refinement\0${[...refinedMemoryIds, ...refined.retiredMemoryIds].sort().join('\0')}`)
+                            .digest('hex').slice(0, 24)}`;
+                        if (memory.finalizeTurnDecision) {
+                            await memory.finalizeTurnDecision({
+                                turnEventId: pending.eventId,
+                                sessionId,
+                                turnId: pending.turnId,
+                                receiptId: refinementReceiptId,
+                                status: 'committed',
+                                memoryIds: refinedMemoryIds,
+                                reason: 'host_explicit_semantic_refinement',
+                            });
+                        }
+                        for (const memoryId of refinedMemoryIds) {
+                            database.enqueueWork({
+                                idempotencyKey: `vector:${String(projectRoot)}:${memoryId}`,
+                                kind: 'memory.vector_backfill',
+                                projectRoot: String(projectRoot),
+                                sessionId,
+                                turnId: pending.turnId,
+                                payload: { observationId: memoryId },
+                                maxAttempts: 20,
+                            });
+                        }
+                        database.insertEvent({
+                            kind: 'memory_semantic_refinement',
+                            timestamp: Date.now(),
+                            success: true,
+                            metadata: {
+                                projectRoot: String(projectRoot), sessionId, turnId: pending.turnId,
+                                receiptId: pending.receiptId, refinementReceiptId,
+                                accepted: refinedMemoryIds.length,
+                                retired: refined.retiredMemoryIds.length,
+                                operations: refined.operations,
+                            },
+                        });
+                        return {
+                            ...replayMemoryDecision(pending),
+                            replayed: false,
+                            refined: true,
+                            refinementReceiptId,
+                            data: {
+                                acceptedCandidates: validation.accepted.map(candidate => ({
+                                    index: candidate.index,
+                                    type: candidate.type,
+                                    disposition: candidate.disposition,
+                                    normalizedFrom: candidate.normalizedFrom,
+                                })),
+                                rejectedCandidates: validation.rejected,
+                                refinedMemoryIds,
+                                retiredMemoryIds: refined.retiredMemoryIds,
+                                operations: refined.operations,
+                                fallbackReceiptPreserved: true,
+                            },
+                        };
+                    }
+                    catch (error) {
+                        const reason = error.message;
+                        database.insertEvent({
+                            kind: 'memory_semantic_refinement',
+                            timestamp: Date.now(),
+                            success: false,
+                            metadata: {
+                                projectRoot: String(projectRoot), sessionId, turnId: pending.turnId,
+                                receiptId: pending.receiptId, reason,
+                                fallback: 'deterministic_explicit_memory',
+                            },
+                        });
+                        emitSemanticControlLog({
+                            event: 'memory.write.degraded',
+                            identity: { projectRoot: String(projectRoot), sessionId, turnId: pending.turnId },
+                            level: 'warn',
+                            timestamp: Date.now(),
+                            data: { stage: 'explicit_host_refinement', reason, fallback: 'deterministic_explicit_memory' },
+                        });
+                        return {
+                            ...replayMemoryDecision(pending),
+                            status: 'degraded',
+                            replayed: false,
+                            refined: false,
+                            degradation: { reason, fallback: 'deterministic_explicit_memory' },
+                        };
+                    }
+                }
+                const durableParsed = parsed.filter(candidate => candidate.disposition !== 'turn_constraint');
+                if (durableParsed.length === 0) {
+                    return {
+                        ...rejectedToolResult('NO_DURABLE_MEMORY_CANDIDATES', 'All candidates were classified as turn constraints. Call memory_skip_turn for this turn.', false),
+                        committed: false,
+                        acceptedCandidates: validation.accepted.map(candidate => ({
+                            index: candidate.index,
+                            disposition: candidate.disposition,
+                        })),
+                    };
+                }
                 let saved;
                 try {
-                    saved = await memory.saveTurnObservations(pending.eventId, sessionId, parsed);
+                    saved = await memory.saveTurnObservations(pending.eventId, sessionId, durableParsed);
                 }
                 catch (error) {
                     const reason = error.message;
@@ -1172,6 +1417,23 @@ export function createToolHandlers(engines, boundProjectRoot) {
                     receiptId,
                     reason: skipReason,
                 });
+                emitSemanticControlLog({
+                    event: 'memory.semantic.decided',
+                    identity: {
+                        projectRoot: String(projectRoot),
+                        sessionId,
+                        turnId: pending.turnId,
+                        actionReceipt: receipt.receiptId,
+                    },
+                    level: 'info',
+                    timestamp: Date.now(),
+                    data: {
+                        status: 'skipped',
+                        operations: [],
+                        memoryIds: [],
+                        reason: skipReason.slice(0, 500),
+                    },
+                });
                 if (memory.finalizeTurnDecision && receipt.receiptId) {
                     try {
                         await memory.finalizeTurnDecision({
@@ -1254,7 +1516,12 @@ export function createToolHandlers(engines, boundProjectRoot) {
                     vectorQueueStatus = 'queued';
                 }
                 catch (error) {
-                    console.error('[devflow] Unable to enqueue distilled memory vector backfill:', error.message);
+                    emitSemanticControlLog({
+                        event: 'memory.write.degraded',
+                        identity: { projectRoot: canonicalProjectRoot, sessionId: typeof _devflow_session_id === 'string' ? _devflow_session_id : undefined },
+                        level: 'warn', timestamp: Date.now(),
+                        data: { stage: 'distill_vector_enqueue', batchId, reason: error.message, fallback: 'lexical_memory_ready' },
+                    });
                 }
                 finally {
                     database.close();