windows-exe-decompiler-mcp-server 0.1.0

package/dist/workflows/semantic-name-review.js

@@ -0,0 +1,521 @@
+/**
+ * workflow.semantic_name_review
+ * High-level orchestration for semantic naming review plus optional reconstruct export refresh.
+ */
+import { z } from 'zod';
+import { createCodeFunctionRenameReviewHandler } from '../tools/code-function-rename-review.js';
+import { createReconstructWorkflowHandler } from './reconstruct.js';
+import { AnalysisProvenanceSchema } from '../analysis-provenance.js';
+import { AnalysisSelectionDiffSchema } from '../selection-diff.js';
+const TOOL_NAME = 'workflow.semantic_name_review';
+export const semanticNameReviewWorkflowInputSchema = z
+    .object({
+    sample_id: z.string().describe('Sample ID (format: sha256:<hex>)'),
+    address: z.string().optional().describe('Optional specific function address'),
+    symbol: z.string().optional().describe('Optional specific function symbol'),
+    topk: z
+        .number()
+        .int()
+        .min(1)
+        .max(20)
+        .default(6)
+        .describe('When address/symbol not provided, review up to top-K functions'),
+    max_functions: z
+        .number()
+        .int()
+        .min(1)
+        .max(20)
+        .default(6)
+        .describe('Maximum number of functions included in the naming review bundle'),
+    include_resolved: z
+        .boolean()
+        .default(false)
+        .describe('Include already resolved functions in the initial review request'),
+    auto_include_resolved_on_empty: z
+        .boolean()
+        .default(true)
+        .describe('Retry in audit mode with include_resolved=true when unresolved selection is empty'),
+    analysis_goal: z
+        .string()
+        .min(1)
+        .max(400)
+        .default('Reverse-engineer the prepared functions and propose precise human-readable semantic names.')
+        .describe('Human-readable analysis goal injected into the MCP prompt and sampling request'),
+    session_tag: z
+        .string()
+        .optional()
+        .describe('Optional semantic naming session tag used for artifact grouping'),
+    evidence_scope: z
+        .enum(['all', 'latest', 'session'])
+        .default('all')
+        .describe('Runtime evidence scope forwarded to review and optional reconstruct/export refresh'),
+    evidence_session_tag: z
+        .string()
+        .optional()
+        .describe('Optional runtime evidence session selector used when evidence_scope=session or to narrow all/latest results'),
+    semantic_scope: z
+        .enum(['all', 'latest', 'session'])
+        .default('all')
+        .describe('Semantic naming artifact scope used for review and optional reconstruct/export refresh'),
+    semantic_session_tag: z
+        .string()
+        .optional()
+        .describe('Optional semantic naming session selector used when semantic_scope=session or to narrow all/latest results'),
+    compare_evidence_scope: z
+        .enum(['all', 'latest', 'session'])
+        .optional()
+        .describe('Optional baseline runtime evidence scope used when refreshing export for comparison-aware workflow output'),
+    compare_evidence_session_tag: z
+        .string()
+        .optional()
+        .describe('Optional baseline runtime evidence session selector used when compare_evidence_scope=session'),
+    compare_semantic_scope: z
+        .enum(['all', 'latest', 'session'])
+        .optional()
+        .describe('Optional baseline semantic artifact scope used when refreshing export for comparison-aware workflow output'),
+    compare_semantic_session_tag: z
+        .string()
+        .optional()
+        .describe('Optional baseline semantic artifact session selector used when compare_semantic_scope=session'),
+    persist_artifact: z
+        .boolean()
+        .default(true)
+        .describe('Persist the prepare bundle artifact before requesting external semantic review'),
+    auto_apply: z
+        .boolean()
+        .default(true)
+        .describe('Persist accepted suggestions automatically via code.function.rename.apply'),
+    rerun_reconstruct: z
+        .boolean()
+        .default(true)
+        .describe('Rerun code.functions.reconstruct after apply to materialize llm/hybrid validated names'),
+    temperature: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0.2)
+        .describe('Sampling temperature passed to the connected MCP client'),
+    max_tokens: z
+        .number()
+        .int()
+        .min(200)
+        .max(8000)
+        .default(1800)
+        .describe('Maximum sampling tokens requested from the connected MCP client'),
+    include_context: z
+        .enum(['none', 'thisServer', 'allServers'])
+        .default('none')
+        .describe('Requested MCP sampling context scope; clients may ignore this preference'),
+    model_hint: z
+        .string()
+        .min(1)
+        .max(120)
+        .optional()
+        .describe('Optional advisory model-family hint for client-mediated MCP sampling'),
+    cost_priority: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0.1)
+        .describe('Advisory model selection preference for sampling cost'),
+    speed_priority: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0.2)
+        .describe('Advisory model selection preference for sampling latency'),
+    intelligence_priority: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0.95)
+        .describe('Advisory model selection preference for reasoning quality'),
+    system_prompt: z
+        .string()
+        .min(1)
+        .max(800)
+        .optional()
+        .describe('Optional extra system prompt for the client-mediated semantic naming review'),
+    rerun_export: z
+        .boolean()
+        .default(true)
+        .describe('After successful apply, rerun workflow.reconstruct to refresh rewrite/export output'),
+    export_path: z
+        .enum(['auto', 'native', 'dotnet'])
+        .default('auto')
+        .describe('Routing strategy used when rerun_export=true'),
+    export_topk: z
+        .number()
+        .int()
+        .min(1)
+        .max(40)
+        .default(12)
+        .describe('Top-K high-value functions used for optional reconstruct/export refresh'),
+    export_name: z
+        .string()
+        .min(1)
+        .max(64)
+        .optional()
+        .describe('Optional export folder name used for the refresh run'),
+    include_plan: z
+        .boolean()
+        .default(false)
+        .describe('Include code.reconstruct.plan when rerun_export=true'),
+    include_obfuscation_fallback: z
+        .boolean()
+        .default(true)
+        .describe('When routing to .NET path, generate IL fallback notes when needed'),
+    fallback_on_error: z
+        .boolean()
+        .default(true)
+        .describe('When primary export path fails, automatically try the alternative path'),
+    allow_partial: z
+        .boolean()
+        .default(true)
+        .describe('When all export paths fail, still return runtime/plan as partial output'),
+    validate_build: z
+        .boolean()
+        .default(false)
+        .describe('Compile the refreshed native reconstruction when rerun_export=true'),
+    run_harness: z
+        .boolean()
+        .default(false)
+        .describe('Execute reconstruct_harness after a successful refreshed native build'),
+    compiler_path: z
+        .string()
+        .min(1)
+        .max(260)
+        .optional()
+        .describe('Optional explicit clang compiler path for the refresh run'),
+    build_timeout_ms: z
+        .number()
+        .int()
+        .min(5000)
+        .max(300000)
+        .default(60000)
+        .describe('Timeout for native clang build validation in milliseconds'),
+    run_timeout_ms: z
+        .number()
+        .int()
+        .min(5000)
+        .max(300000)
+        .default(30000)
+        .describe('Timeout for reconstruct_harness execution in milliseconds'),
+    reuse_cached: z
+        .boolean()
+        .default(true)
+        .describe('Reuse cached reconstruct workflow results for the optional refresh run'),
+})
+    .refine((value) => value.evidence_scope !== 'session' || Boolean(value.evidence_session_tag?.trim()), {
+    message: 'evidence_session_tag is required when evidence_scope=session',
+    path: ['evidence_session_tag'],
+})
+    .refine((value) => value.semantic_scope !== 'session' || Boolean(value.semantic_session_tag?.trim()), {
+    message: 'semantic_session_tag is required when semantic_scope=session',
+    path: ['semantic_session_tag'],
+})
+    .refine((value) => value.compare_evidence_scope !== 'session' || Boolean(value.compare_evidence_session_tag?.trim()), {
+    message: 'compare_evidence_session_tag is required when compare_evidence_scope=session',
+    path: ['compare_evidence_session_tag'],
+})
+    .refine((value) => value.compare_semantic_scope !== 'session' || Boolean(value.compare_semantic_session_tag?.trim()), {
+    message: 'compare_semantic_session_tag is required when compare_semantic_scope=session',
+    path: ['compare_semantic_session_tag'],
+});
+export const semanticNameReviewWorkflowOutputSchema = z.object({
+    ok: z.boolean(),
+    data: z
+        .object({
+        sample_id: z.string(),
+        review: z.object({
+            review_status: z.string(),
+            prompt_name: z.string(),
+            client: z.object({
+                name: z.string().nullable(),
+                version: z.string().nullable(),
+                sampling_available: z.boolean(),
+            }),
+            prepare: z.object({
+                prepared_count: z.number().int().nonnegative(),
+                unresolved_count: z.number().int().nonnegative(),
+                include_resolved: z.boolean(),
+                artifact_id: z.string().nullable(),
+            }),
+            sampling: z.object({
+                attempted: z.boolean(),
+                model: z.string().nullable(),
+                stop_reason: z.string().nullable(),
+                parsed_suggestion_count: z.number().int().nonnegative(),
+            }),
+            apply: z.object({
+                attempted: z.boolean(),
+                accepted_count: z.number().int().nonnegative(),
+                rejected_count: z.number().int().nonnegative(),
+                artifact_id: z.string().nullable(),
+            }),
+            confidence_policy: z.object({
+                calibrated: z.boolean(),
+                rule_priority_over_llm: z.boolean(),
+                llm_acceptance_threshold: z.number().min(0).max(1),
+                meaning: z.string(),
+            }),
+            reconstruct: z.object({
+                attempted: z.boolean(),
+                reconstructed_count: z.number().int().nonnegative(),
+                llm_or_hybrid_count: z.number().int().nonnegative(),
+                functions: z.array(z.object({
+                    function: z.string(),
+                    address: z.string(),
+                    validated_name: z.string().nullable(),
+                    resolution_source: z.string().nullable(),
+                })),
+            }),
+        }),
+        export: z.object({
+            attempted: z.boolean(),
+            status: z.enum(['completed', 'failed', 'skipped']),
+            selected_path: z.enum(['native', 'dotnet']).nullable(),
+            export_tool: z.string().nullable(),
+            export_root: z.string().nullable(),
+            manifest_path: z.string().nullable(),
+            build_validation_status: z.string().nullable(),
+            harness_validation_status: z.string().nullable(),
+            provenance: AnalysisProvenanceSchema.nullable(),
+            selection_diffs: AnalysisSelectionDiffSchema.nullable(),
+            notes: z.array(z.string()),
+        }),
+        next_steps: z.array(z.string()),
+    })
+        .optional(),
+    warnings: z.array(z.string()).optional(),
+    errors: z.array(z.string()).optional(),
+    artifacts: z.array(z.any()).optional(),
+    metrics: z
+        .object({
+        elapsed_ms: z.number(),
+        tool: z.string(),
+    })
+        .optional(),
+});
+export const semanticNameReviewWorkflowToolDefinition = {
+    name: TOOL_NAME,
+    description: 'Run semantic naming review end-to-end for any MCP-capable LLM client, then optionally refresh reconstruct/export output with the applied names.',
+    inputSchema: semanticNameReviewWorkflowInputSchema,
+    outputSchema: semanticNameReviewWorkflowOutputSchema,
+};
+export function createSemanticNameReviewWorkflowHandler(workspaceManager, database, cacheManager, mcpServer, dependencies) {
+    const renameReviewHandler = dependencies?.renameReviewHandler ||
+        createCodeFunctionRenameReviewHandler(workspaceManager, database, cacheManager, mcpServer);
+    const reconstructWorkflowHandler = dependencies?.reconstructWorkflowHandler ||
+        createReconstructWorkflowHandler(workspaceManager, database, cacheManager);
+    return async (args) => {
+        const startTime = Date.now();
+        const warnings = [];
+        const errors = [];
+        const artifacts = [];
+        try {
+            const input = semanticNameReviewWorkflowInputSchema.parse(args);
+            const reviewResult = await renameReviewHandler({
+                sample_id: input.sample_id,
+                address: input.address,
+                symbol: input.symbol,
+                topk: input.topk,
+                max_functions: input.max_functions,
+                include_resolved: input.include_resolved,
+                auto_include_resolved_on_empty: input.auto_include_resolved_on_empty,
+                analysis_goal: input.analysis_goal,
+                session_tag: input.session_tag,
+                evidence_scope: input.evidence_scope,
+                evidence_session_tag: input.evidence_session_tag,
+                semantic_scope: input.semantic_scope,
+                semantic_session_tag: input.semantic_session_tag,
+                persist_artifact: input.persist_artifact,
+                auto_apply: input.auto_apply,
+                rerun_reconstruct: input.rerun_reconstruct,
+                temperature: input.temperature,
+                max_tokens: input.max_tokens,
+                include_context: input.include_context,
+                model_hint: input.model_hint,
+                cost_priority: input.cost_priority,
+                speed_priority: input.speed_priority,
+                intelligence_priority: input.intelligence_priority,
+                system_prompt: input.system_prompt,
+            });
+            warnings.push(...(reviewResult.warnings || []));
+            artifacts.push(...(reviewResult.artifacts || []));
+            if (!reviewResult.ok) {
+                return {
+                    ok: false,
+                    errors: reviewResult.errors || ['code.function.rename.review failed'],
+                    warnings: warnings.length > 0 ? warnings : undefined,
+                    artifacts: artifacts.length > 0 ? artifacts : undefined,
+                    metrics: {
+                        elapsed_ms: Date.now() - startTime,
+                        tool: TOOL_NAME,
+                    },
+                };
+            }
+            const reviewData = (reviewResult.data || {});
+            const acceptedCount = Number(reviewData?.apply?.accepted_count || 0);
+            const llmOrHybridCount = Number(reviewData?.reconstruct?.llm_or_hybrid_count || 0);
+            const canRefreshExport = input.rerun_export &&
+                reviewData.review_status === 'sampled_and_applied' &&
+                (acceptedCount > 0 || llmOrHybridCount > 0);
+            let exportSummary = {
+                attempted: false,
+                status: 'skipped',
+                selected_path: null,
+                export_tool: null,
+                export_root: null,
+                manifest_path: null,
+                build_validation_status: null,
+                harness_validation_status: null,
+                provenance: null,
+                selection_diffs: null,
+                notes: [],
+            };
+            if (canRefreshExport) {
+                const exportResult = await reconstructWorkflowHandler({
+                    sample_id: input.sample_id,
+                    path: input.export_path,
+                    topk: input.export_topk,
+                    export_name: input.export_name,
+                    validate_build: input.validate_build,
+                    run_harness: input.run_harness,
+                    compiler_path: input.compiler_path,
+                    build_timeout_ms: input.build_timeout_ms,
+                    run_timeout_ms: input.run_timeout_ms,
+                    evidence_scope: input.evidence_scope,
+                    evidence_session_tag: input.evidence_session_tag,
+                    compare_evidence_scope: input.compare_evidence_scope,
+                    compare_evidence_session_tag: input.compare_evidence_session_tag,
+                    semantic_scope: input.semantic_scope === 'all' && input.session_tag ? 'session' : input.semantic_scope,
+                    semantic_session_tag: input.semantic_session_tag || input.session_tag,
+                    compare_semantic_scope: input.compare_semantic_scope,
+                    compare_semantic_session_tag: input.compare_semantic_session_tag,
+                    include_plan: input.include_plan,
+                    include_obfuscation_fallback: input.include_obfuscation_fallback,
+                    fallback_on_error: input.fallback_on_error,
+                    allow_partial: input.allow_partial,
+                    reuse_cached: input.reuse_cached,
+                });
+                warnings.push(...(exportResult.warnings || []));
+                artifacts.push(...(exportResult.artifacts || []));
+                if (!exportResult.ok) {
+                    errors.push(...(exportResult.errors || ['workflow.reconstruct failed during export refresh']));
+                    exportSummary = {
+                        attempted: true,
+                        status: 'failed',
+                        selected_path: null,
+                        export_tool: null,
+                        export_root: null,
+                        manifest_path: null,
+                        build_validation_status: null,
+                        harness_validation_status: null,
+                        provenance: null,
+                        selection_diffs: null,
+                        notes: ['Refresh export failed after semantic name apply.'],
+                    };
+                }
+                else {
+                    const exportData = (exportResult.data || {});
+                    exportSummary = {
+                        attempted: true,
+                        status: 'completed',
+                        selected_path: exportData.selected_path || null,
+                        export_tool: exportData.export?.tool || null,
+                        export_root: exportData.export?.export_root || null,
+                        manifest_path: exportData.export?.manifest_path || null,
+                        build_validation_status: exportData.export?.build_validation_status || null,
+                        harness_validation_status: exportData.export?.harness_validation_status || null,
+                        provenance: exportData.provenance || null,
+                        selection_diffs: exportData.selection_diffs || null,
+                        notes: Array.isArray(exportData.notes) ? exportData.notes : [],
+                    };
+                }
+            }
+            else if (input.rerun_export) {
+                exportSummary.notes.push(reviewData.review_status === 'prompt_contract_only'
+                    ? 'Refresh export skipped because no sampled suggestions were applied yet.'
+                    : 'Refresh export skipped because no llm/hybrid name updates were materialized.');
+            }
+            const nextSteps = [
+                ...(Array.isArray(reviewData.next_steps) ? reviewData.next_steps : []),
+                ...exportSummary.notes,
+            ];
+            return {
+                ok: errors.length === 0,
+                data: {
+                    sample_id: input.sample_id,
+                    review: {
+                        review_status: reviewData.review_status || 'unknown',
+                        prompt_name: reviewData.prompt_name || 'reverse.semantic_name_review',
+                        client: {
+                            name: reviewData.client?.name || null,
+                            version: reviewData.client?.version || null,
+                            sampling_available: Boolean(reviewData.client?.sampling_available),
+                        },
+                        prepare: {
+                            prepared_count: Number(reviewData.prepare?.prepared_count || 0),
+                            unresolved_count: Number(reviewData.prepare?.unresolved_count || 0),
+                            include_resolved: Boolean(reviewData.prepare?.include_resolved),
+                            artifact_id: reviewData.prepare?.artifact_id || null,
+                        },
+                        sampling: {
+                            attempted: Boolean(reviewData.sampling?.attempted),
+                            model: reviewData.sampling?.model || null,
+                            stop_reason: reviewData.sampling?.stop_reason || null,
+                            parsed_suggestion_count: Number(reviewData.sampling?.parsed_suggestion_count || 0),
+                        },
+                        apply: {
+                            attempted: Boolean(reviewData.apply?.attempted),
+                            accepted_count: acceptedCount,
+                            rejected_count: Number(reviewData.apply?.rejected_count || 0),
+                            artifact_id: reviewData.apply?.artifact_id || null,
+                        },
+                        confidence_policy: {
+                            calibrated: Boolean(reviewData.confidence_policy?.calibrated),
+                            rule_priority_over_llm: reviewData.confidence_policy?.rule_priority_over_llm !== false,
+                            llm_acceptance_threshold: Number(reviewData.confidence_policy?.llm_acceptance_threshold ?? 0.62),
+                            meaning: String(reviewData.confidence_policy?.meaning ||
+                                'Naming confidence remains heuristic. Rule-based names currently take priority, and pure LLM suggestions are promoted only after meeting the acceptance threshold.'),
+                        },
+                        reconstruct: {
+                            attempted: Boolean(reviewData.reconstruct?.attempted),
+                            reconstructed_count: Number(reviewData.reconstruct?.reconstructed_count || 0),
+                            llm_or_hybrid_count: llmOrHybridCount,
+                            functions: Array.isArray(reviewData.reconstruct?.functions)
+                                ? reviewData.reconstruct.functions.map((item) => ({
+                                    function: String(item.function || ''),
+                                    address: String(item.address || ''),
+                                    validated_name: item.validated_name || null,
+                                    resolution_source: item.resolution_source || null,
+                                }))
+                                : [],
+                        },
+                    },
+                    export: exportSummary,
+                    next_steps: nextSteps,
+                },
+                warnings: warnings.length > 0 ? warnings : undefined,
+                errors: errors.length > 0 ? errors : undefined,
+                artifacts: artifacts.length > 0 ? artifacts : undefined,
+                metrics: {
+                    elapsed_ms: Date.now() - startTime,
+                    tool: TOOL_NAME,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                errors: [error instanceof Error ? error.message : String(error)],
+                metrics: {
+                    elapsed_ms: Date.now() - startTime,
+                    tool: TOOL_NAME,
+                },
+            };
+        }
+    };
+}
+//# sourceMappingURL=semantic-name-review.js.map