atabey 0.0.12 → 0.0.14

package/framework-mcp/dist/framework-mcp/src/tools/compliance/mask_pii.js

@@ -0,0 +1,55 @@
+import { classifyData, containsPII, maskObject, maskText } from "../../../../src/shared/pii.js";
+export function handleMaskPII(root, args) {
+    const mode = args.mode || "auto";
+    const strictMode = args.strictMode ?? false;
+    // Mode: text
+    if (mode === "text" || (mode === "auto" && args.text && !args.data)) {
+        if (!args.text) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: "[ERROR] 'text' parameter is required when mode is 'text'." }],
+            };
+        }
+        const masked = maskText(args.text);
+        const hasPII = containsPII(args.text);
+        const classification = classifyData(args.text);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        originalLength: args.text.length,
+                        maskedLength: masked.length,
+                        hasPII,
+                        classification,
+                        masked,
+                    }, null, 2),
+                }],
+        };
+    }
+    // Mode: object
+    if (mode === "object" || (mode === "auto" && args.data)) {
+        if (!args.data) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: "[ERROR] 'data' parameter is required when mode is 'object'." }],
+            };
+        }
+        const masked = maskObject(args.data, 0, strictMode);
+        const hasPII = containsPII(JSON.stringify(args.data));
+        const classification = classifyData(JSON.stringify(args.data));
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        hasPII,
+                        classification,
+                        masked,
+                    }, null, 2),
+                }],
+        };
+    }
+    return {
+        isError: true,
+        content: [{ type: "text", text: "[ERROR] Provide either 'text' (string) or 'data' (object) parameter." }],
+    };
+}

package/framework-mcp/dist/framework-mcp/src/tools/definitions.js

@@ -1,5 +1,5 @@
-import * as schemas from "./schemas.js";
 import { zodToMcpSchema } from "../utils/zod-to-mcp.js";
+import * as schemas from "./schemas.js";
 /**
  * ─── SUPREME TOOL REGISTRY ─────────────────────────────────────────
  * Every tool is dynamically generated from its Zod schema.
@@ -172,4 +172,27 @@ export const TOOLS = [
         description: "Pause execution and ask the human developer a clarifying question via the terminal.",
         inputSchema: zodToMcpSchema(schemas.AskHumanSchema),
     },
+    // ─── PII / Compliance ─────────────────────────────────────────
+    {
+        name: "mask_pii",
+        description: "Mask Personally Identifiable Information (PII) in text or structured data. Compliant with KVKK (Law No. 6698) and GDPR. Detects and masks emails, phone numbers, TC IDs, API keys, tokens, IPs, credit cards, IBANs, and more.",
+        inputSchema: zodToMcpSchema(schemas.MaskPIISchema),
+    },
+    // ─── Code Quality ─────────────────────────────────────────────
+    {
+        name: "analyze_code_quality",
+        description: "Analyze code quality in a given path. Checks TypeScript types, lint rules, and code complexity.",
+        inputSchema: zodToMcpSchema(schemas.AnalyzeCodeQualitySchema),
+    },
+    {
+        name: "check_architecture_compliance",
+        description: "Check architecture compliance in a given path. Verifies layer boundaries (Controller→Service→Repository), import direction rules, and strict mode.",
+        inputSchema: zodToMcpSchema(schemas.CheckArchitectureComplianceSchema),
+    },
+    // ─── Human-in-the-Loop ────────────────────────────────────────
+    {
+        name: "approve_operation",
+        description: "Approve, reject, or list pending risk-gated operations. Use this when an operation was blocked by the Risk Gate (risk score ≥ 60). Action: 'approve' | 'reject' | 'list'.",
+        inputSchema: zodToMcpSchema(schemas.ApproveOperationSchema),
+    },
 ];

package/framework-mcp/dist/framework-mcp/src/tools/framework/run_tests.js

@@ -1,11 +1,36 @@
 import { execSync } from "child_process";
 import { getBackendLanguage, getDefaultTestCommand } from "../../utils/cli.js";
+const TEST_COMMAND_ALLOW_LIST = [
+    "npm test",
+    "npm run test",
+    "npx vitest",
+    "pytest",
+    "go test",
+    "dotnet test",
+    "mvn test",
+    "./gradlew test",
+    "cargo test"
+];
 /**
  * Executes project tests and returns results for agent analysis.
  */
 export function handleRunTests(projectRoot, args) {
     const language = getBackendLanguage(projectRoot);
     const testCommand = args.command || getDefaultTestCommand(language);
+    // Validate command to prevent shell injection / chaining
+    const isAllowed = TEST_COMMAND_ALLOW_LIST.some(allowedCmd => testCommand.startsWith(allowedCmd));
+    if (!isAllowed) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `[ERROR] Test command not allowed: "${testCommand}". Must start with one of: ${TEST_COMMAND_ALLOW_LIST.join(", ")}` }]
+        };
+    }
+    if (/[;&|><$`\n\r]/.test(testCommand)) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: "[ERROR] Test command rejected: Shell metacharacters are forbidden to prevent command injection." }]
+        };
+    }
     try {
         const output = execSync(testCommand, { cwd: projectRoot, encoding: "utf8", stdio: "pipe" });
         return {

package/framework-mcp/dist/framework-mcp/src/tools/gateway/llm_gateway_query.js

@@ -0,0 +1,137 @@
+/**
+ * ATABEY MCP Tool — LLM Gateway Query
+ *
+ * Sends a chat completion request through the ATABEY LLM Gateway.
+ * The gateway automatically selects the best provider based on the
+ * configured load balancing strategy (failover, round-robin, cost-optimized, etc.)
+ *
+ * This tool allows ANY MCP-connected AI (Gemini CLI, Claude CLI, Cursor, Grok, etc.)
+ * to route LLM requests through the gateway to any supported provider.
+ *
+ * The gateway module is loaded dynamically from the project root at runtime,
+ * not at compile time (since it lives outside the MCP workspace).
+ */
+import path from "path";
+/**
+ * Dynamically load the LLM Gateway from the project root.
+ * Falls back gracefully if the gateway module is not available.
+ */
+async function loadGateway(projectRoot) {
+    try {
+        const gatewayPath = path.join(projectRoot, "dist/src/modules/gateway/index.js");
+        const mod = await import(gatewayPath);
+        return mod.gateway;
+    }
+    catch {
+        try {
+            // Fallback: try tsx resolution for development
+            const gatewayPath = path.join(projectRoot, "src/modules/gateway/index.ts");
+            const mod = await import(gatewayPath);
+            return mod.gateway;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Handle llm_gateway_query tool call.
+ * Routes the request through the LLM Gateway with load balancing.
+ */
+export async function handleLLMGatewayQuery(projectRoot, args) {
+    const startTime = Date.now();
+    try {
+        // Load gateway dynamically
+        const gateway = await loadGateway(projectRoot);
+        if (!gateway) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: "LLM Gateway is not initialized. The project may need to be built first. " +
+                                "Run: npm run build:core",
+                            solution: "Gateway module not found at dist/src/modules/gateway/index.js. " +
+                                "Ensure the main package is built and ATABEY_PROJECT_ROOT is set correctly.",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        // Build gateway request
+        const gatewayRequest = {
+            messages: args.messages.map(m => ({
+                role: m.role,
+                content: m.content,
+            })),
+            system: args.system,
+            model: args.model,
+            temperature: args.temperature ?? 0.7,
+            maxTokens: args.maxTokens ?? 4096,
+            traceId: args.traceId || `MCP-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`,
+        };
+        // Provider override
+        if (args.provider) {
+            gatewayRequest.provider = args.provider;
+        }
+        // Strategy override
+        if (args.strategy) {
+            gatewayRequest.strategy = args.strategy;
+        }
+        // Send through gateway
+        const response = await gateway.chat(gatewayRequest);
+        const elapsed = Date.now() - startTime;
+        if (response.success) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            content: response.content,
+                            provider: response.provider,
+                            model: response.model,
+                            usage: response.usage,
+                            latencyMs: response.latencyMs,
+                            cost: response.cost,
+                            traceId: response.traceId,
+                            elapsed,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: false,
+                        error: response.content,
+                        provider: response.provider,
+                        traceId: response.traceId,
+                        elapsed,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: false,
+                        error: `Gateway query failed: ${error.message}`,
+                        elapsed: Date.now() - startTime,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+}

package/framework-mcp/dist/framework-mcp/src/tools/gateway/llm_gateway_status.js

@@ -0,0 +1,90 @@
+/**
+ * ATABEY MCP Tool — LLM Gateway Status
+ *
+ * Returns the current status of the LLM Gateway, including provider health,
+ * current load balancing strategy, usage statistics, and budget info.
+ *
+ * Useful for monitoring and debugging gateway behavior without CLI access.
+ */
+import path from "path";
+/**
+ * Dynamically load the LLM Gateway from the project root.
+ */
+async function loadGateway(projectRoot) {
+    try {
+        const gatewayPath = path.join(projectRoot, "dist/src/modules/gateway/index.js");
+        const mod = await import(gatewayPath);
+        return mod.gateway;
+    }
+    catch {
+        try {
+            const gatewayPath = path.join(projectRoot, "src/modules/gateway/index.ts");
+            const mod = await import(gatewayPath);
+            return mod.gateway;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Handle llm_gateway_status tool call.
+ */
+export async function handleLLMGatewayStatus(projectRoot, args) {
+    const detail = args.detail || "overview";
+    try {
+        const gateway = await loadGateway(projectRoot);
+        if (!gateway) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            status: "unavailable",
+                            message: "LLM Gateway is not initialized. " +
+                                "Build the project first with: npm run build:core",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const result = {
+            status: "active",
+            strategy: gateway.loadBalancer.getStrategy(),
+        };
+        if (detail === "providers" || detail === "overview") {
+            result.providers = gateway.getProviderHealth();
+        }
+        if (detail === "stats" || detail === "overview") {
+            result.stats = gateway.getStats();
+        }
+        if (detail === "overview" || detail === "stats") {
+            const budget = gateway.costTracker.getBudgetStatus();
+            if (budget) {
+                result.budget = budget;
+            }
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        status: "error",
+                        error: `Failed to get gateway status: ${error.message}`,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+}

package/framework-mcp/dist/framework-mcp/src/tools/index.js

@@ -1,35 +1,39 @@
+import { handleMaskPII } from "./compliance/mask_pii.js";
+import { handleAcquireLock, handleReleaseLock } from "./control_plane/locking.js";
+import { handleRegisterAgent } from "./control_plane/registry.js";
 import { TOOLS } from "./definitions.js";
-import { handleReadFile } from "./file_system/read_file.js";
-import { handleWriteFile } from "./file_system/write_file.js";
-import { handleReplaceText } from "./file_system/replace_text.js";
 import { handleBatchSurgicalEdit } from "./file_system/batch_surgical_edit.js";
 import { handlePatchFile } from "./file_system/patch_file.js";
-import { handleGrepSearch } from "./search/grep_search.js";
-import { handleListDir } from "./search/list_dir.js";
-import { handleGetProjectGaps } from "./search/get_gaps.js";
-import { handleGetProjectMap } from "./search/get_map.js";
-import { handleGetFrameworkStatus } from "./framework/get_status.js";
-import { handleUpdateProjectMemory } from "./framework/update_memory.js";
+import { handleReadFile } from "./file_system/read_file.js";
+import { handleReplaceText } from "./file_system/replace_text.js";
+import { handleWriteFile } from "./file_system/write_file.js";
 import { handleAuditDependencies } from "./framework/audit_deps.js";
-import { handleRunTests } from "./framework/run_tests.js";
-import { handleGetSystemHealth } from "./observability/get_health.js";
-import { handleCheckPorts } from "./observability/check_ports.js";
+import { handleGetFrameworkStatus } from "./framework/get_status.js";
 import { handleOrchestrateLoop } from "./framework/orchestrate.js";
+import { handleRunTests } from "./framework/run_tests.js";
 import { handleSubmitPlan } from "./framework/submit_plan.js";
 import { handleUpdateContractHash } from "./framework/update_contract_hash.js";
-import { handleReadProjectMemory } from "./memory/read_memory.js";
+import { handleUpdateProjectMemory } from "./framework/update_memory.js";
+import { handleDeleteKnowledge } from "./memory/delete_knowledge.js";
 import { handleGetMemoryInsights } from "./memory/get_insights.js";
-import { handleStoreKnowledge } from "./memory/store_knowledge.js";
+import { handleReadProjectMemory } from "./memory/read_memory.js";
 import { handleSearchKnowledge } from "./memory/search_knowledge.js";
-import { handleDeleteKnowledge } from "./memory/delete_knowledge.js";
-import { handleSendAgentMessage } from "./messaging/send_message.js";
-import { handleLogAgentAction } from "./messaging/log_action.js";
+import { handleStoreKnowledge } from "./memory/store_knowledge.js";
 import { handleAskHuman } from "./messaging/ask_human.js";
-import { handleAcquireLock, handleReleaseLock } from "./control_plane/locking.js";
-import { handleRegisterAgent } from "./control_plane/registry.js";
-import { handleRunCommand } from "./shell/run_command.js";
+import { handleApproveOperation } from "./messaging/approve_operation.js";
+import { handleLogAgentAction } from "./messaging/log_action.js";
+import { handleSendAgentMessage } from "./messaging/send_message.js";
+import { handleCheckPorts } from "./observability/check_ports.js";
+import { handleGetSystemHealth } from "./observability/get_health.js";
+import { handleAnalyzeCodeQuality } from "./quality/analyze_code_quality.js";
+import { handleCheckArchitectureCompliance } from "./quality/check_architecture_compliance.js";
 import { handleCheckLint } from "./quality/check_lint.js";
 import * as schemas from "./schemas.js";
+import { handleGetProjectGaps } from "./search/get_gaps.js";
+import { handleGetProjectMap } from "./search/get_map.js";
+import { handleGrepSearch } from "./search/grep_search.js";
+import { handleListDir } from "./search/list_dir.js";
+import { handleRunCommand } from "./shell/run_command.js";
 // Map of tool names to their handler functions
 const bind = (fn) => {
     return (root, args) => fn(root, args);
@@ -61,12 +65,16 @@ export const toolHandlers = {
     send_agent_message: bind(handleSendAgentMessage),
     log_agent_action: bind(handleLogAgentAction),
     ask_human: bind(handleAskHuman),
+    approve_operation: bind(handleApproveOperation),
     update_contract_hash: bind(handleUpdateContractHash),
     acquire_lock: bind(handleAcquireLock),
     release_lock: bind(handleReleaseLock),
     register_agent: bind(handleRegisterAgent),
     run_shell_command: bind(handleRunCommand),
     check_lint: bind(handleCheckLint),
+    analyze_code_quality: bind(handleAnalyzeCodeQuality),
+    check_architecture_compliance: bind(handleCheckArchitectureCompliance),
+    mask_pii: bind(handleMaskPII),
 };
 // Map of tool names to their Zod validation schemas
 export const toolSchemas = {
@@ -107,5 +115,11 @@ export const toolSchemas = {
     send_agent_message: schemas.SendAgentMessageSchema,
     log_agent_action: schemas.LogAgentActionSchema,
     ask_human: schemas.AskHumanSchema,
+    approve_operation: schemas.ApproveOperationSchema,
+    // Code Quality
+    analyze_code_quality: schemas.AnalyzeCodeQualitySchema,
+    check_architecture_compliance: schemas.CheckArchitectureComplianceSchema,
+    // PII / Compliance
+    mask_pii: schemas.MaskPIISchema,
 };
 export { TOOLS };

package/framework-mcp/dist/framework-mcp/src/tools/messaging/approve_operation.js

@@ -0,0 +1,80 @@
+import { approveOperation, rejectOperation, getPendingApprovals } from "../../utils/human-in-loop.js";
+/**
+ * ─── APPROVE OPERATION — In-Chat Risk Gate ──────────────────────────
+ *
+ * AI CLI kullanımında "atabey approve <traceId>" CLI komutu çalıştırmak mümkün
+ * değildir — chat'e yazılan şey CLI komutu olarak değil mesaj olarak işlenir.
+ *
+ * Bu tool, risk gate approval flow'unu doğrudan MCP tool çağrısına taşır:
+ *
+ * 1. Atabey yüksek riskli bir operasyonu bloklar
+ * 2. Geliştiriciye: "approve_operation tool'unu çağır" der
+ * 3. AI bu tool'u çağırır → operasyon onaylanır/reddedilir
+ *
+ * Geliştirici terminale geçmek zorunda kalmaz.
+ */
+export async function handleApproveOperation(_root, args) {
+    const { action, traceId, reason } = args;
+    // LIST: Bekleyen approval'ları göster
+    if (action === "list") {
+        const pending = getPendingApprovals();
+        if (pending.length === 0) {
+            return {
+                content: [{ type: "text", text: "[APPROVALS] No pending operations waiting for approval." }],
+            };
+        }
+        const lines = [
+            `[APPROVALS] ${pending.length} pending operation(s):\n`,
+            ...pending.map(req => [
+                "  ─────────────────────────────────────",
+                `  Trace ID:   ${req.traceId}`,
+                `  Tool:       ${req.toolName}`,
+                `  Agent:      ${req.agent}`,
+                `  Risk Score: ${req.riskScore}/100 (${req.riskLevel})`,
+                `  Reason:     ${req.reason}`,
+                `  Expires:    ${new Date(req.expiresAt).toISOString()}`,
+            ].join("\n")),
+            "",
+            "To approve: call approve_operation with action=\"approve\" and traceId=\"<id>\"",
+            "To reject:  call approve_operation with action=\"reject\" and traceId=\"<id>\"",
+        ];
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+        };
+    }
+    // APPROVE or REJECT: traceId zorunlu
+    if (!traceId) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `[ERROR] traceId is required for "${action}" action.` }],
+        };
+    }
+    if (action === "approve") {
+        const result = approveOperation(traceId);
+        return {
+            content: [{
+                    type: "text",
+                    text: result.success
+                        ? `[APPROVED] ✅ ${result.message}\nYou may retry the blocked operation now.`
+                        : `[ERROR] ${result.message}`,
+                }],
+            isError: !result.success,
+        };
+    }
+    if (action === "reject") {
+        const result = rejectOperation(traceId);
+        return {
+            content: [{
+                    type: "text",
+                    text: result.success
+                        ? `[REJECTED] ⛔ ${result.message}${reason ? `\nReason: ${reason}` : ""}`
+                        : `[ERROR] ${result.message}`,
+                }],
+            isError: !result.success,
+        };
+    }
+    return {
+        isError: true,
+        content: [{ type: "text", text: `[ERROR] Unknown action: "${String(action)}". Use "approve", "reject", or "list".` }],
+    };
+}

package/framework-mcp/dist/framework-mcp/src/tools/messaging/ask_human.js

@@ -1,30 +1,99 @@
-import chalk from "chalk";
+import fs from "fs";
+import path from "path";
+/**
+ * ─── ASK HUMAN — File Bridge ─────────────────────────────────────────
+ *
+ * AI CLI'lar (Claude Code, Gemini CLI) MCP server'ı stdio subprocess olarak
+ * başlatır. Bu subprocess'te stdin isTTY=false olur (MCP JSON-RPC için kullanılır).
+ *
+ * Çözüm: File-based Q&A bridge.
+ * 1. Soru → .atabey/hitl/question.txt dosyasına yazılır
+ * 2. Geliştirici `atabey hitl` komutuyla cevap girer
+ * 3. Cevap → .atabey/hitl/answer.txt dosyasına yazılır
+ * 4. Bu handler cevabı okur ve AI'ya döner
+ *
+ * Dashboard: /api/approvals endpoint'i üzerinden web dashboard'dan da cevaplanabilir.
+ */
 export async function handleAskHuman(root, args) {
-    if (process.env.ATABEY_TEST_DIR || !process.stdin.isTTY) {
-        return { content: [{ type: "text", text: "[SKIPPED] Non-interactive environment. Cannot ask human." }] };
-    }
+    const timeoutSeconds = args.timeoutSeconds ?? 120;
+    const hitlDir = path.join(root, ".atabey", "hitl");
+    const questionFile = path.join(hitlDir, "question.txt");
+    const answerFile = path.join(hitlDir, "answer.txt");
     try {
-        const readline = await import("readline");
-        const rl = readline.createInterface({
-            input: process.stdin,
-            output: process.stdout
-        });
-        return new Promise((resolve) => {
-            process.stdout.write("\n" + chalk.bgMagenta.white.bold(" [HUMAN-IN-THE-LOOP REQUIRED] ") + "\n");
-            process.stdout.write(chalk.magenta("An agent has paused execution to ask you a question:\n"));
-            rl.question(`\n${chalk.bold(args.question)}\n${chalk.gray("> ")}`, (answer) => {
-                rl.close();
-                resolve({
-                    content: [{ type: "text", text: `[HUMAN RESPONSE] ${answer}` }]
-                });
-            });
-        });
+        // Ensure hitl directory exists
+        fs.mkdirSync(hitlDir, { recursive: true });
+        // Clear any stale answer file
+        if (fs.existsSync(answerFile)) {
+            fs.unlinkSync(answerFile);
+        }
+        // Write the question with metadata
+        const questionPayload = JSON.stringify({
+            timestamp: new Date().toISOString(),
+            question: args.question,
+            timeoutAt: new Date(Date.now() + timeoutSeconds * 1000).toISOString(),
+        }, null, 2);
+        fs.writeFileSync(questionFile, questionPayload);
+        // Write human-readable prompt file alongside
+        fs.writeFileSync(path.join(hitlDir, "PENDING.txt"), [
+            "═══════════════════════════════════════════════════",
+            " [ATABEY] AGENT WAITING FOR YOUR ANSWER",
+            "═══════════════════════════════════════════════════",
+            "",
+            `QUESTION: ${args.question}`,
+            "",
+            "To answer, run in your terminal:",
+            "  atabey hitl answer \"your answer here\"",
+            "",
+            "Or use the dashboard: http://localhost:5858",
+            "═══════════════════════════════════════════════════",
+        ].join("\n"));
+        process.stderr.write(`[HITL] Question written to ${questionFile}\n`);
+        process.stderr.write("[HITL] Run: atabey hitl answer \"your answer\"\n");
+        // Poll for answer file
+        const pollIntervalMs = 1000;
+        const maxAttempts = timeoutSeconds;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+            if (fs.existsSync(answerFile)) {
+                const answer = fs.readFileSync(answerFile, "utf8").trim();
+                // Clean up
+                try {
+                    fs.unlinkSync(questionFile);
+                    fs.unlinkSync(answerFile);
+                    const pendingFile = path.join(hitlDir, "PENDING.txt");
+                    if (fs.existsSync(pendingFile))
+                        fs.unlinkSync(pendingFile);
+                }
+                catch { /* cleanup is best-effort */ }
+                process.stderr.write("[HITL] Answer received.\n");
+                return {
+                    content: [{ type: "text", text: `[HUMAN RESPONSE] ${answer}` }],
+                };
+            }
+        }
+        // Timeout — clean up question file
+        try {
+            if (fs.existsSync(questionFile))
+                fs.unlinkSync(questionFile);
+            const pendingFile = path.join(hitlDir, "PENDING.txt");
+            if (fs.existsSync(pendingFile))
+                fs.unlinkSync(pendingFile);
+        }
+        catch { /* cleanup is best-effort */ }
+        return {
+            content: [{
+                    type: "text",
+                    text: `[HITL TIMEOUT] No answer received within ${timeoutSeconds}s.\n` +
+                        `Question was: "${args.question}"\n` +
+                        "To answer pending questions, run: atabey hitl answer \"your answer\"",
+                }],
+        };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         return {
             isError: true,
-            content: [{ type: "text", text: `[ERROR] Failed to ask human: ${message}` }]
+            content: [{ type: "text", text: `[ERROR] ask_human failed: ${message}` }],
         };
     }
 }

package/framework-mcp/dist/framework-mcp/src/tools/observability/check_ports.js

@@ -3,7 +3,9 @@ import { execSync } from "child_process";
  * Checks for active network ports and their status.
  */
 export function handleCheckPorts(projectRoot, args) {
-    const filter = args.filter || ""; // Optional filter (e.g., ":3000")
+    const rawFilter = args.filter || "";
+    // Sanitize filter to prevent command injection (allow only alphanumeric, dots, colons, dashes, underscores)
+    const filter = rawFilter.replace(/[^a-zA-Z0-9.:_-]/g, "");
     try {
         // Using 'lsof -i -P -n' to list open files and network connections
         // Note: may require permissions or behave differently on non-Unix systems