@devflow-tools/mcp-server 0.17.3 → 0.17.4

package/dist/tools.d.ts

@@ -1,5 +1,6 @@
 import { type EngineSet } from "@devflow-tools/context-engine";
-import type { DevFlowPlugin } from "@devflow-tools/sdk";
+import { type ChannelQueryPlan, type DevFlowPlugin, type ImmutableTaskIntentArtifact } from "@devflow-tools/sdk";
+import type { SemanticSamplingResolver } from './semantic-sampling-resolver.js';
 export interface ToolDef {
     name: string;
     description: string;
@@ -20,7 +21,28 @@ export declare const GUARDED_CORE_TOOL_NAMES: ReadonlySet<string>;
 export declare function getGuardedToolNames(pluginTools: readonly Pick<ToolDef, "name">[]): ReadonlySet<string>;
 export declare function getCoreTools(knowledgeScopes?: string[]): ToolDef[];
 export type ToolHandlers = Record<string, (args: Record<string, unknown>) => Promise<unknown>>;
-export declare function createToolHandlers(engines: EngineSet, boundProjectRoot: string): ToolHandlers;
+declare function resolveBoundContextTask(input: {
+    projectRoot: string;
+    sessionId?: string;
+    requestId?: string;
+    turnId?: string;
+    intentArtifactHash?: string;
+    agentQuery: string;
+    expandedTerms?: string;
+}): {
+    query: string;
+    expandedTerms?: string;
+    requestId?: string;
+    turnId?: string;
+    intentArtifact?: ImmutableTaskIntentArtifact;
+    queryPlan?: ChannelQueryPlan;
+};
+export declare function resolveBoundContextTaskWithSemantics(input: Parameters<typeof resolveBoundContextTask>[0], engines: EngineSet, dependencies: ToolHandlerDependencies): Promise<ReturnType<typeof resolveBoundContextTask>>;
+export interface ToolHandlerDependencies {
+    semanticSampling?: SemanticSamplingResolver;
+}
+export declare function createToolHandlers(engines: EngineSet, boundProjectRoot: string, dependencies?: ToolHandlerDependencies): ToolHandlers;
 export declare function getPluginTools(plugins: DevFlowPlugin[]): ToolDef[];
 export declare function createPluginHandlers(engines: EngineSet, plugins: DevFlowPlugin[], boundProjectRoot: string): Record<string, (args: Record<string, unknown>) => Promise<unknown>>;
+export {};
 //# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAEV,aAAa,EAGd,MAAM,oBAAoB,CAAC;AAoB5B,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,WAAW,CAAC,EAAE;QACZ,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;CACH;AAED,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CActD,CAAC;AA0BH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,SAAS,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,GAC5C,WAAW,CAAC,MAAM,CAAC,CAKrB;AAED,wBAAgB,YAAY,CAAC,eAAe,GAAE,MAAM,EAAO,GAAG,OAAO,EAAE,CAwWtE;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;AAkT/F,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,GAAG,YAAY,CA+kC7F;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,OAAO,EAAE,CAqClE;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,SAAS,EAClB,OAAO,EAAE,aAAa,EAAE,EACxB,gBAAgB,EAAE,MAAM,GACvB,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAkErE"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/tools.js

@@ -1,4 +1,5 @@
-import { getKnowledgeResult, getMemoryResult, getProjectContextResult, } from "@devflow-tools/context-engine";
+import { buildChannelQueryPlan, buildRetrievalTaskPlan, extractStructuralSemanticEvidence, getKnowledgeResult, getMemoryResult, getProjectContextResult, mergeSemanticAuthority, parseIntent, } from "@devflow-tools/context-engine";
+import { assertTaskSemanticFrameV2, projectSemanticFrameToLegacyIntent, resolveSemanticResolutionMode, } from "@devflow-tools/sdk";
 import { resolveCapabilityRollout } from "@devflow-tools/sdk/capability-rollout";
 import { canonicalizeProjectRoot, wrapHandlerRequireRoot } from "./plugin-guards.js";
 import { getReportResourceUri, readToolReport } from "./report-store.js";
@@ -640,15 +641,303 @@ function resolveBoundContextTask(input) {
         database.close();
     }
 }
+export async function resolveBoundContextTaskWithSemantics(input, engines, dependencies) {
+    const legacy = resolveBoundContextTask(input);
+    const artifact = legacy.intentArtifact;
+    if (!artifact)
+        return legacy;
+    const semanticMode = resolveSemanticResolutionMode(input.projectRoot);
+    if (semanticMode === 'off' || !engines.semanticRouter)
+        return legacy;
+    const database = openGlobalDevFlowDatabase(undefined, { busyTimeoutMs: 250 });
+    try {
+        const latest = database.getLatestSemanticResolution(artifact.identity.projectRoot, artifact.identity.sessionId, artifact.identity.turnId);
+        if (!latest)
+            return legacy;
+        if (latest.artifactRevision >= 2) {
+            const resolvedArtifact = database.getTaskIntentArtifact(latest.artifactHash);
+            const resolvedPlan = resolvedArtifact && database.getChannelQueryPlanForIntent({
+                projectRoot: resolvedArtifact.projectRoot,
+                sessionId: resolvedArtifact.sessionId,
+                turnId: resolvedArtifact.turnId,
+                sourceIntentHash: resolvedArtifact.artifactHash,
+            });
+            if (resolvedArtifact && resolvedPlan && semanticMode !== 'shadow') {
+                return boundTaskFromRecords(legacy, resolvedArtifact, resolvedPlan);
+            }
+            return legacy;
+        }
+        let provisional;
+        try {
+            assertTaskSemanticFrameV2(latest.frame, artifact.normalizedPrompt);
+            provisional = latest.frame;
+        }
+        catch {
+            return legacy;
+        }
+        const structural = extractStructuralSemanticEvidence({
+            prompt: artifact.normalizedPrompt,
+            command: artifact.command,
+            targetAnchors: artifact.targetAnchors,
+        });
+        const route = await engines.semanticRouter.route(structural.normalizedPrompt);
+        emitSemanticControlLog({
+            event: 'semantic.route.scored',
+            identity: { ...artifact.identity, intentArtifactHash: artifact.artifactHash },
+            level: route.status === 'unavailable' ? 'warn' : 'info',
+            timestamp: Date.now(),
+            data: {
+                mode: semanticMode,
+                status: route.status,
+                modelId: route.modelId,
+                modelRevision: route.modelRevision,
+                thresholdVersion: route.thresholdVersion,
+                margin: route.margin,
+                candidates: route.candidates.slice(0, 8),
+                latencyMs: route.latencyMs,
+                reason: route.reason,
+            },
+        });
+        emitSemanticControlLog({
+            event: 'semantic.model.profile_evaluated',
+            identity: { ...artifact.identity, intentArtifactHash: artifact.artifactHash },
+            level: 'debug', timestamp: Date.now(),
+            data: {
+                mode: semanticMode, modelId: route.modelId, modelRevision: route.modelRevision,
+                thresholdVersion: route.thresholdVersion, catalogVersion: provisional.resolver.routeCatalogVersion,
+                status: route.status, latencyMs: route.latencyMs,
+            },
+        });
+        let sampled;
+        if ((route.status === 'escalation_required' || hasCompositionalStructure(structural))
+            && dependencies.semanticSampling) {
+            emitSemanticControlLog({
+                event: 'semantic.resolution.escalated', identity: artifact.identity, level: 'info', timestamp: Date.now(),
+                data: { mode: semanticMode, frameHash: provisional.frameHash, reason: route.reason },
+            });
+            sampled = await dependencies.semanticSampling({
+                normalizedPrompt: structural.normalizedPrompt,
+                sourceHash: artifact.sourceHash,
+                structural,
+                route,
+                provisionalFrame: provisional,
+                timeoutMs: 3_000,
+            });
+        }
+        const resolved = mergeSemanticAuthority({
+            sourceHash: artifact.sourceHash,
+            structural,
+            route,
+            ...(sampled?.status === 'resolved' && sampled.frame ? { sampledFrame: sampled.frame } : {}),
+            provisionalFrame: provisional,
+        });
+        const finalResolution = withSamplingResult(resolved, sampled);
+        const projection = projectSemanticFrameToLegacyIntent(finalResolution.frame);
+        const revisedBody = {
+            ...artifact,
+            version: 2,
+            supersedesHash: artifact.artifactHash,
+            intent: projection.intent,
+            action: projection.action,
+            entities: finalResolution.frame.entities,
+            targetAnchors: finalResolution.frame.targetAnchors,
+            policyConstraints: finalResolution.frame.constraints,
+            classificationEvidence: finalResolution.frame.evidence.flatMap((evidence) => {
+                const field = evidence.field === 'negation' || evidence.field === 'condition'
+                    ? 'constraint'
+                    : evidence.field;
+                if (field !== 'intent' && field !== 'action' && field !== 'entity'
+                    && field !== 'target' && field !== 'constraint')
+                    return [];
+                const source = evidence.source === 'structural'
+                    || evidence.source === 'lexical_feature'
+                    ? 'deterministic_parser'
+                    : evidence.source === 'host_sampling'
+                        ? 'host_semantic'
+                        : evidence.source;
+                return [{
+                        source,
+                        field,
+                        value: evidence.value,
+                        reason: `semantic_frame:${finalResolution.frame.frameHash}`,
+                        confidence: evidence.confidence,
+                    }];
+            }),
+            createdAt: finalResolution.frame.createdAt,
+        };
+        const { artifactHash: _oldHash, ...unhashedArtifact } = revisedBody;
+        const revisedArtifact = {
+            ...unhashedArtifact,
+            artifactHash: hashCanonical(unhashedArtifact),
+        };
+        const taskPlan = buildRetrievalTaskPlan({
+            query: legacy.query,
+            parsedIntent: parseIntent(legacy.query),
+            targetAnchors: revisedArtifact.targetAnchors,
+            activeSkill: revisedArtifact.activeSkill,
+            command: revisedArtifact.command,
+            authoritativeArtifact: revisedArtifact,
+            semanticFrame: finalResolution.frame,
+        });
+        const revisedPlan = buildChannelQueryPlan({
+            artifact: revisedArtifact,
+            taskPlan,
+            expandedTerms: legacy.expandedTerms,
+            generatedBy: 'hybrid',
+        });
+        database.appendTaskIntentArtifact(toTaskIntentRecord(revisedArtifact));
+        database.appendChannelQueryPlan(toChannelQueryPlanRecord(revisedPlan));
+        database.appendSemanticResolution({
+            frameHash: finalResolution.frame.frameHash,
+            ...artifact.identity,
+            sourceHash: artifact.sourceHash,
+            artifactHash: revisedArtifact.artifactHash,
+            artifactRevision: 2,
+            supersedesFrameHash: provisional.frameHash,
+            state: finalResolution.frame.state,
+            generatedBy: finalResolution.frame.resolver.generatedBy,
+            modelId: finalResolution.frame.resolver.modelId,
+            modelRevision: finalResolution.frame.resolver.modelRevision,
+            routeCatalogVersion: finalResolution.frame.resolver.routeCatalogVersion,
+            thresholdVersion: finalResolution.frame.resolver.thresholdVersion,
+            route: finalResolution.route,
+            sampling: finalResolution.sampling,
+            conflicts: finalResolution.conflicts,
+            frame: finalResolution.frame,
+            durationMs: Math.round(finalResolution.route.latencyMs + (finalResolution.sampling.latencyMs ?? 0)),
+            createdAt: finalResolution.frame.createdAt,
+        });
+        logSemanticResolution(artifact, semanticMode, finalResolution, projection);
+        return semanticMode === 'shadow'
+            ? legacy
+            : { ...legacy, intentArtifact: revisedArtifact, queryPlan: revisedPlan };
+    }
+    finally {
+        database.close();
+    }
+}
+function boundTaskFromRecords(legacy, artifactRecord, planRecord) {
+    return {
+        ...legacy,
+        intentArtifact: toSdkIntentArtifact(artifactRecord),
+        queryPlan: toSdkChannelQueryPlan(planRecord),
+    };
+}
+function hasCompositionalStructure(structural) {
+    return structural.conditions.length > 0 || structural.prohibitions.length > 0
+        || new Set(structural.positiveActionSpans.map(item => item.value)).size > 1;
+}
+function withSamplingResult(resolution, sampled) {
+    if (!sampled)
+        return resolution;
+    return {
+        ...resolution,
+        sampling: {
+            attempted: true,
+            status: sampled.status,
+            ...(sampled.model ? { model: sampled.model } : {}),
+            latencyMs: sampled.latencyMs,
+            ...(sampled.responseHash ? { responseHash: sampled.responseHash } : {}),
+        },
+    };
+}
+function logSemanticResolution(artifact, mode, resolution, projection) {
+    const event = resolution.frame.state === 'resolved'
+        ? 'semantic.resolution.completed'
+        : 'semantic.resolution.abstained';
+    emitSemanticControlLog({
+        event, identity: { ...artifact.identity, intentArtifactHash: artifact.artifactHash },
+        level: resolution.frame.state === 'resolved' ? 'info' : 'warn', timestamp: Date.now(),
+        data: {
+            mode, frameHash: resolution.frame.frameHash, state: resolution.frame.state,
+            permission: resolution.frame.mutationPermission, intent: projection.intent,
+            action: projection.action, samplingStatus: resolution.sampling.status,
+            conflictCount: resolution.conflicts.length,
+        },
+    });
+    if (resolution.conflicts.length > 0)
+        emitSemanticControlLog({
+            event: 'semantic.authority.conflicted', identity: artifact.identity, level: 'warn', timestamp: Date.now(),
+            data: { frameHash: resolution.frame.frameHash, conflicts: resolution.conflicts },
+        });
+    if (projection.intent !== artifact.intent || projection.action !== artifact.action)
+        emitSemanticControlLog({
+            event: 'semantic.regex.shadow_mismatch', identity: artifact.identity, level: 'info', timestamp: Date.now(),
+            data: { mode, frameHash: resolution.frame.frameHash, legacyIntent: artifact.intent,
+                legacyAction: artifact.action, semanticIntent: projection.intent, semanticAction: projection.action },
+        });
+}
+function toTaskIntentRecord(artifact) {
+    return {
+        ...artifact.identity, version: artifact.version, supersedesHash: artifact.supersedesHash,
+        rawPrompt: artifact.rawPrompt, normalizedPrompt: artifact.normalizedPrompt,
+        command: artifact.command, slashArgs: artifact.slashArgs, activeSkill: artifact.activeSkill,
+        intent: artifact.intent, action: artifact.action, entities: artifact.entities,
+        targetAnchors: artifact.targetAnchors, policyConstraints: artifact.policyConstraints,
+        classificationEvidence: artifact.classificationEvidence.map(item => ({ ...item })),
+        sourceEventIds: artifact.sourceEventIds, sourceHash: artifact.sourceHash,
+        artifactHash: artifact.artifactHash, createdAt: artifact.createdAt,
+    };
+}
+function toChannelQueryPlanRecord(plan) {
+    return {
+        ...plan.identity, sourceIntentHash: plan.sourceIntentHash, planHash: plan.planHash,
+        code: plan.code.map(item => ({ ...item })), memory: plan.memory.map(item => ({ ...item })),
+        knowledge: plan.knowledge.map(item => ({ ...item })), generatedBy: plan.generatedBy,
+        ...(plan.degradation ? { degradation: { ...plan.degradation } } : {}), createdAt: plan.createdAt,
+    };
+}
+function toSdkIntentArtifact(record) {
+    return {
+        identity: { projectRoot: record.projectRoot, projectId: record.projectId, hostId: record.hostId,
+            sessionId: record.sessionId, turnId: record.turnId, requestId: record.requestId,
+            ...(record.executionId ? { executionId: record.executionId } : {}) },
+        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,
+    };
+}
+function toSdkChannelQueryPlan(record) {
+    return { identity: { projectRoot: record.projectRoot, projectId: record.projectId, hostId: record.hostId,
+            sessionId: record.sessionId, turnId: record.turnId, requestId: record.requestId,
+            ...(record.executionId ? { executionId: record.executionId } : {}) },
+        sourceIntentHash: record.sourceIntentHash, planHash: record.planHash, code: record.code,
+        memory: record.memory, knowledge: record.knowledge, generatedBy: record.generatedBy,
+        ...(record.degradation ? { degradation: record.degradation } : {}), createdAt: record.createdAt };
+}
+function hashCanonical(value) {
+    return createHash('sha256').update(stableCanonicalJson(value)).digest('hex');
+}
+function stableCanonicalJson(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? JSON.stringify(value) : 'null';
+    if (Array.isArray(value))
+        return `[${value.map(stableCanonicalJson).join(',')}]`;
+    if (!value || typeof value !== 'object')
+        return JSON.stringify(String(value));
+    const record = value;
+    return `{${Object.keys(record).sort().filter(key => record[key] !== undefined)
+        .map(key => `${JSON.stringify(key)}:${stableCanonicalJson(record[key])}`).join(',')}}`;
+}
 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) {
+export function createToolHandlers(engines, boundProjectRoot, dependencies = {}) {
     const hasBoundProjectRoot = typeof boundProjectRoot === 'string' && boundProjectRoot.trim().length > 0;
     const canonicalProjectRoot = canonicalizeProjectRoot(String(boundProjectRoot ?? process.cwd()));
+    // Resolution is invoked by the rollout-aware context path in the next stage.
+    // Retaining the injected dependency here keeps handler construction backward compatible.
+    void dependencies.semanticSampling;
     function getFreshnessMs() {
         try {
             const stats = engines.codegraph.getStats();
@@ -660,7 +949,7 @@ 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_turn_id, _devflow_intent_artifact_hash, _devflow_active_skill, activeSkill }) => {
-            const boundTask = resolveBoundContextTask({
+            const boundTask = await resolveBoundContextTaskWithSemantics({
                 projectRoot: canonicalProjectRoot,
                 sessionId: typeof _devflow_session_id === 'string' ? _devflow_session_id : undefined,
                 requestId: typeof _devflow_request_id === 'string' ? _devflow_request_id : undefined,
@@ -668,7 +957,7 @@ export function createToolHandlers(engines, boundProjectRoot) {
                 intentArtifactHash: typeof _devflow_intent_artifact_hash === 'string' ? _devflow_intent_artifact_hash : undefined,
                 agentQuery: query,
                 expandedTerms: typeof expandedTerms === 'string' ? expandedTerms : undefined,
-            });
+            }, engines, dependencies);
             return getProjectContextResult(engines.context, {
                 query: boundTask.query,
                 mode: mode ?? "fast",