@hopping-dev/hub 0.1.0

package/dist/mcp/tools.js

@@ -0,0 +1,1217 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._resetAskMode = _resetAskMode;
+exports.getAskMode = getAskMode;
+exports.getToolDefinitions = getToolDefinitions;
+exports.createToolHandler = createToolHandler;
+const crypto_1 = require("crypto");
+const package_json_1 = __importDefault(require("../../package.json"));
+const schemas_1 = require("./schemas");
+const cloud_1 = require("../cloud");
+const manager_1 = require("../config/manager");
+const file_extractor_1 = require("./file-extractor");
+const summary_1 = require("./summary");
+const risk_level_1 = require("./risk-level");
+const tool_mapping_1 = require("../policy/tool-mapping");
+// 從 package.json 讀取版本號（避免硬編碼）
+const HUB_VERSION = package_json_1.default.version;
+// ============================================
+// Ask Mode State (REQ-HUB-041)
+// ============================================
+/** Hub 記憶體中的 Ask Mode（新 Session 自動 reset 為 'local'） */
+let askMode = 'local';
+/** 供測試用：重設 askMode（Hub 重啟模擬） */
+function _resetAskMode() {
+    askMode = 'local';
+}
+/** 取得當前 askMode（供 IpcWatcher 及測試使用） */
+function getAskMode() {
+    return askMode;
+}
+// ============================================
+// Tool Definitions
+// ============================================
+function getToolDefinitions() {
+    return [
+        {
+            name: 'hopping.check',
+            description: 'Request approval for a tool before executing it. Hub evaluates the request against local policies and returns ALLOW or DENY.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    toolName: {
+                        type: 'string',
+                        description: 'The name of the tool to be checked',
+                    },
+                    toolInput: {
+                        type: 'object',
+                        description: 'The input parameters of the tool to be checked',
+                    },
+                    sessionId: {
+                        type: 'string',
+                        description: 'Current session ID',
+                    },
+                    cwd: {
+                        type: 'string',
+                        description: 'Current working directory',
+                    },
+                    context: {
+                        type: 'object',
+                        description: 'Additional context including task information',
+                        properties: {
+                            recentFiles: { type: 'array', items: { type: 'string' } },
+                            branch: { type: 'string' },
+                            project: { type: 'string' },
+                            taskDescription: { type: 'string', description: 'What task the agent is working on' },
+                            reasoning: { type: 'string', description: 'Why this operation is needed' },
+                            userPrompt: {
+                                type: 'string',
+                                description: "The user's original prompt (stored locally only)",
+                            },
+                        },
+                    },
+                },
+                required: ['toolName', 'toolInput'],
+            },
+        },
+        {
+            name: 'hopping.report',
+            description: 'Report a completed operation to Hub for logging and observation. Used by agents without Hook support.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    toolName: {
+                        type: 'string',
+                        description: 'The name of the tool that was executed',
+                    },
+                    toolParams: {
+                        type: 'object',
+                        description: 'Parameters passed to the tool',
+                    },
+                    result: {
+                        type: 'string',
+                        description: 'Execution result summary',
+                    },
+                    duration: {
+                        type: 'number',
+                        description: 'Execution duration in milliseconds',
+                    },
+                    success: {
+                        type: 'boolean',
+                        description: 'Whether the execution was successful',
+                    },
+                    filePaths: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'File paths affected by the operation',
+                    },
+                },
+                required: ['toolName'],
+            },
+        },
+        {
+            name: 'hopping.status',
+            description: 'Query the current status of the HopPing Hub.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: {
+                        type: 'string',
+                        enum: ['sessions', 'pending', 'stats', 'all'],
+                        description: 'Type of status query',
+                    },
+                    agentId: {
+                        type: 'string',
+                        description: 'Filter by specific agent ID',
+                    },
+                },
+            },
+        },
+        {
+            name: 'hopping.respond',
+            description: 'Submit a local approval decision for a pending operation. Used when hopping.check returned decision="pending" and the user is at the computer to approve or deny locally.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    approvalId: {
+                        type: 'string',
+                        description: 'The approvalId returned by hopping.check when decision was "pending"',
+                    },
+                    decision: {
+                        type: 'string',
+                        enum: ['approved', 'denied'],
+                        description: 'The user decision: "approved" or "denied"',
+                    },
+                    reason: {
+                        type: 'string',
+                        description: 'Optional reason for the decision',
+                    },
+                },
+                required: ['approvalId', 'decision'],
+            },
+        },
+        {
+            name: 'hopping.pair',
+            description: 'Pair this Hub with a HopPing account using a pairing code. Run this once to link the Hub to your mobile app. The token is saved locally and used automatically on future starts.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    pairingCode: {
+                        type: 'string',
+                        description: 'The 6-character pairing code shown in the HopPing mobile app',
+                    },
+                    cloudUrl: {
+                        type: 'string',
+                        description: 'Override the Cloud Backend URL (optional, defaults to HOPPING_CLOUD_URL)',
+                    },
+                },
+                required: ['pairingCode'],
+            },
+        },
+        {
+            name: 'hopping.mode',
+            description: 'Switch between local and away mode. Local mode (default): hopping.ask returns immediately, agent asks the user directly. Away mode: hopping.ask sends questions to the mobile app and waits for response.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    mode: {
+                        type: 'string',
+                        enum: ['local', 'away'],
+                        description: 'The mode to switch to: "local" (user at computer) or "away" (user away)',
+                    },
+                },
+                required: ['mode'],
+            },
+        },
+        {
+            name: 'hopping.ask',
+            description: 'Ask the user a non-approval question (choice or freetext). In local mode, returns immediately so the agent can ask directly. In away mode, sends the question to the mobile app and waits for response.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    question: {
+                        type: 'string',
+                        description: 'The question to ask the user',
+                    },
+                    responseType: {
+                        type: 'string',
+                        enum: ['choice', 'freetext'],
+                        description: 'Expected response format: choice (select from options) or freetext (open input)',
+                    },
+                    options: {
+                        type: 'array',
+                        description: 'Available options for choice responseType',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                id: { type: 'string' },
+                                label: { type: 'string' },
+                                description: { type: 'string' },
+                                isOther: { type: 'boolean' },
+                            },
+                            required: ['id', 'label'],
+                        },
+                    },
+                    placeholder: {
+                        type: 'string',
+                        description: 'Placeholder text for freetext input',
+                    },
+                    context: {
+                        type: 'object',
+                        description: 'Task context for the question',
+                        properties: {
+                            taskDescription: { type: 'string' },
+                            reasoning: { type: 'string' },
+                        },
+                    },
+                },
+                required: ['question', 'responseType'],
+            },
+        },
+    ];
+}
+function validateInput(schema, args) {
+    const parsed = schema.safeParse(args);
+    if (parsed.success) {
+        return { ok: true, data: parsed.data };
+    }
+    const messages = parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+    return {
+        ok: false,
+        result: {
+            content: [
+                { type: 'text', text: JSON.stringify({ error: 'Validation failed', details: messages }) },
+            ],
+            isError: true,
+        },
+    };
+}
+// ============================================
+// Approval Config Helper (S2-HUB-APR-002)
+// ============================================
+async function getApprovalConfigSafe(deps) {
+    if (!deps.configManager)
+        return { ...manager_1.DEFAULT_APPROVAL_CONFIG };
+    try {
+        return await deps.configManager.getApprovalConfig();
+    }
+    catch {
+        return { ...manager_1.DEFAULT_APPROVAL_CONFIG };
+    }
+}
+function buildLocalDecisionMessage(decision, source) {
+    if (decision === 'approved') {
+        return source === 'local_dialog'
+            ? 'Approved locally via dialog'
+            : 'Approved locally via terminal (hopping.respond)';
+    }
+    if (decision === 'denied') {
+        return source === 'local_dialog'
+            ? 'Denied locally via dialog'
+            : 'Denied locally via terminal (hopping.respond)';
+    }
+    // timeout / pending / etc — caller sets the message via buildTimeoutMessage
+    return `Local approval result: ${decision}`;
+}
+function buildTimeoutMessage(onTimeout, riskLevel, timeoutMs) {
+    const seconds = Math.round(timeoutMs / 1000);
+    switch (onTimeout) {
+        case 'pending':
+            return `⏳ Remote approval timed out after ${seconds}s. This ${riskLevel}-risk operation requires your approval. Please approve or deny to proceed.`;
+        case 'timeout':
+            return `Remote approval timed out after ${seconds}s (${riskLevel} risk). Follow Skill rules for timeout decisions.`;
+        case 'denied':
+            return `Denied: remote approval timed out after ${seconds}s (${riskLevel} risk).`;
+        case 'approved':
+            return `Auto-approved after timeout (${seconds}s, ${riskLevel} risk). User configured onTimeout=approved.`;
+        default:
+            return `Remote approval timed out after ${seconds}s.`;
+    }
+}
+// ============================================
+// Store Write Helper (de-duplicated from handleCheck)
+// ============================================
+/** Max chars for taskDescription/reasoning sent to Cloud */
+const TASK_CONTEXT_TRUNCATE_LENGTH = 200;
+function truncateField(value, maxLength) {
+    if (value === undefined)
+        return undefined;
+    if (value.length <= maxLength)
+        return value;
+    return value.slice(0, maxLength - 3) + '...';
+}
+/**
+ * Build taskContext for Cloud payload (security layering: NO userPrompt).
+ */
+function buildTaskContext(context) {
+    if (!context?.taskDescription && !context?.reasoning)
+        return undefined;
+    return {
+        taskDescription: truncateField(context.taskDescription, TASK_CONTEXT_TRUNCATE_LENGTH),
+        reasoning: truncateField(context.reasoning, TASK_CONTEXT_TRUNCATE_LENGTH),
+    };
+}
+/**
+ * Build contextTags JSON for metadata table (includes ALL context fields).
+ */
+function buildContextTags(input) {
+    const tags = {};
+    if (input.context?.branch)
+        tags['branch'] = input.context.branch;
+    if (input.context?.project)
+        tags['project'] = input.context.project;
+    if (input.context?.taskDescription)
+        tags['taskDescription'] = input.context.taskDescription;
+    if (input.context?.reasoning)
+        tags['reasoning'] = input.context.reasoning;
+    if (input.context?.userPrompt)
+        tags['userPrompt'] = input.context.userPrompt;
+    return tags;
+}
+function writeCheckOperation(deps, params) {
+    if (!deps.store)
+        return;
+    deps.store.operations.insert({
+        id: params.id,
+        approvalId: null,
+        toolName: params.toolName,
+        toolParams: params.toolInput ? JSON.stringify(params.toolInput) : null,
+        filePaths: params.filePaths.length > 0 ? JSON.stringify(params.filePaths) : null,
+        riskLevel: params.riskLevel,
+        decision: params.decision,
+        createdAt: params.now,
+        decidedAt: params.now,
+        toolUseId: null,
+        promptType: params.promptType ?? null,
+        responseType: params.responseType ?? null,
+    });
+}
+/**
+ * Write a pending operation (decision=null) to SQLite, awaiting user response.
+ * Used by both Cloud and Local approval paths.
+ */
+function writePendingCheckOperation(deps, params) {
+    if (!deps.store)
+        return;
+    deps.store.operations.insert({
+        id: params.id,
+        approvalId: null,
+        toolName: params.toolName,
+        toolParams: params.toolInput ? JSON.stringify(params.toolInput) : null,
+        filePaths: params.filePaths.length > 0 ? JSON.stringify(params.filePaths) : null,
+        riskLevel: params.riskLevel,
+        decision: null,
+        createdAt: params.now,
+        decidedAt: null,
+        toolUseId: null,
+        promptType: (params.promptType ?? null),
+        responseType: (params.responseType ?? null),
+    });
+}
+/**
+ * Write metadata record for a hopping.check call.
+ */
+function writeCheckMetadata(deps, params) {
+    if (!deps.store)
+        return;
+    const contextTags = buildContextTags(params.input);
+    deps.store.metadata.insert({
+        operationId: params.operationId,
+        agentType: deps.agentType ?? 'generic_mcp',
+        sessionId: params.input.sessionId ?? deps.agentId ?? 'unknown',
+        durationMs: null,
+        tokenUsage: null,
+        contextTags: Object.keys(contextTags).length > 0 ? JSON.stringify(contextTags) : null,
+        source: 'check',
+        resultStatus: null,
+        toolResultSummary: null,
+        createdAt: params.now,
+    });
+}
+// ============================================
+// Tool Handler Factory
+// ============================================
+function createToolHandler(deps) {
+    return async (name, args) => {
+        switch (name) {
+            case 'hopping.check': {
+                const v = validateInput(schemas_1.HoppingCheckInputSchema, args);
+                return v.ok ? handleCheck(v.data, deps) : v.result;
+            }
+            case 'hopping.report': {
+                const v = validateInput(schemas_1.HoppingReportInputSchema, args);
+                return v.ok ? handleReport(v.data, deps) : v.result;
+            }
+            case 'hopping.respond': {
+                const v = validateInput(schemas_1.HoppingRespondInputSchema, args);
+                return v.ok ? handleRespond(v.data, deps) : v.result;
+            }
+            case 'hopping.status': {
+                const v = validateInput(schemas_1.HoppingStatusInputSchema, args);
+                return v.ok ? handleStatus(v.data, deps) : v.result;
+            }
+            case 'hopping.pair': {
+                const v = validateInput(schemas_1.HoppingPairInputSchema, args);
+                return v.ok ? handlePair(v.data, deps) : v.result;
+            }
+            case 'hopping.mode': {
+                const v = validateInput(schemas_1.HoppingModeInputSchema, args);
+                return v.ok ? handleMode(v.data, deps) : v.result;
+            }
+            case 'hopping.ask': {
+                const v = validateInput(schemas_1.HoppingAskInputSchema, args);
+                return v.ok ? handleAsk(v.data, deps) : v.result;
+            }
+            default:
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ error: `Unknown tool: ${name}` }) }],
+                    isError: true,
+                };
+        }
+    };
+}
+// ============================================
+// hopping.check Handler
+// ============================================
+async function handleCheck(input, deps) {
+    const { policyEngine, logger, shouldIntercept } = deps;
+    const approvalId = (0, crypto_1.randomUUID)();
+    const now = new Date().toISOString();
+    // Extract file paths from toolInput (used in all paths)
+    const filePaths = (0, file_extractor_1.extractFilePaths)(input.toolName, input.toolInput);
+    // Dev mode: bypass policy if not intercepting
+    if (!shouldIntercept(input.toolName)) {
+        logger.debug('hopping.check: dev mode bypass', { toolName: input.toolName, approvalId });
+        const output = {
+            approvalId,
+            decision: 'approved',
+            riskLevel: 'low',
+            policyResult: {
+                requestId: approvalId,
+                finalAction: 'ALLOW',
+                triggeredPolicies: [],
+                evaluationTimeMs: 0,
+                evaluatedAt: now,
+            },
+            message: 'Auto-approved (dev mode)',
+            waitedForRemote: false,
+        };
+        writeCheckOperation(deps, {
+            id: approvalId,
+            toolName: input.toolName,
+            toolInput: input.toolInput,
+            filePaths,
+            riskLevel: 'low',
+            decision: 'approved',
+            now,
+        });
+        writeCheckMetadata(deps, { operationId: approvalId, input, now });
+        return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+    }
+    // Build evaluation context
+    const agentId = deps.agentId ?? 'unknown';
+    const agentType = deps.agentType ?? 'generic_mcp';
+    // Three-layer tool mapping resolution
+    const userMappings = deps.configManager ? await deps.configManager.getToolMappings() : null;
+    const bundledRegistry = (0, tool_mapping_1.loadBundledRegistry)();
+    const mappingEntry = (0, tool_mapping_1.resolveToolMapping)(input.toolName, agentType, userMappings, bundledRegistry);
+    const operationFields = (0, tool_mapping_1.extractOperationFields)(mappingEntry, input.toolInput);
+    const context = {
+        requestId: approvalId,
+        agentId,
+        agentType,
+        operation: {
+            type: mappingEntry.type,
+            toolName: input.toolName,
+            target: input.cwd,
+            command: operationFields.command,
+            filePath: operationFields.filePath,
+            apiEndpoint: operationFields.apiEndpoint,
+        },
+        session: {
+            costUsd: 0,
+            durationSeconds: (Date.now() - deps.startTime) / 1000,
+            approvalCount: 0,
+        },
+        timestamp: now,
+    };
+    const policyResult = await policyEngine.evaluate(context);
+    const riskLevel = (0, risk_level_1.deriveRiskLevel)(policyResult.finalAction, input.toolName, input.toolInput);
+    // Generate smart summary
+    const summary = (0, summary_1.generateSummary)(input.toolName, input.toolInput);
+    // Build task context for Cloud (security layering: NO userPrompt)
+    const taskContext = buildTaskContext(input.context);
+    // Handle YOLO mode: auto-approve（policy 仍執行，取得 riskLevel 用於觀測）
+    if (deps.isYoloMode?.()) {
+        const output = {
+            approvalId,
+            decision: 'approved',
+            riskLevel,
+            policyResult,
+            message: 'Auto-approved (YOLO observe mode)',
+            waitedForRemote: false,
+        };
+        writeCheckOperation(deps, {
+            id: approvalId,
+            toolName: input.toolName,
+            toolInput: input.toolInput,
+            filePaths,
+            riskLevel,
+            decision: 'approved',
+            now,
+        });
+        writeCheckMetadata(deps, { operationId: approvalId, input, now });
+        const cloudAgentId = deps.cloudConnector?.cloudAgentId ?? agentId;
+        if (deps.cloudConnector?.isConnected) {
+            deps.cloudConnector.sendProgressUpdate((0, risk_level_1.buildYoloProgressPayload)({
+                agentId: cloudAgentId,
+                sessionId: input.sessionId ?? cloudAgentId,
+                toolName: input.toolName,
+                riskLevel,
+                timestamp: now,
+                filePaths: filePaths.length > 0 ? filePaths : undefined,
+            }));
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+    }
+    // Handle ALLOW
+    if (policyResult.finalAction === 'ALLOW') {
+        const output = {
+            approvalId,
+            decision: 'approved',
+            riskLevel,
+            policyResult,
+            message: 'Approved by local policy',
+            waitedForRemote: false,
+        };
+        writeCheckOperation(deps, {
+            id: approvalId,
+            toolName: input.toolName,
+            toolInput: input.toolInput,
+            filePaths,
+            riskLevel,
+            decision: 'approved',
+            now,
+        });
+        writeCheckMetadata(deps, { operationId: approvalId, input, now });
+        if (deps.cloudConnector?.isConnected) {
+            const cloudAgentId = deps.cloudConnector.cloudAgentId ?? agentId;
+            deps.cloudConnector.sendProgressUpdate({
+                agentId: cloudAgentId,
+                sessionId: input.sessionId ?? cloudAgentId,
+                message: `✅ ${input.toolName} 自動核准`,
+                timestamp: now,
+                messageType: 'operation_report',
+            });
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+    }
+    // S4-HUB-DONTASK-001: Session memory check — auto-approve if user previously chose "don't ask again"
+    if (deps.sessionMemory?.has(input.toolName, riskLevel)) {
+        logger.info('hopping.check: session memory hit — auto-approve', {
+            toolName: input.toolName,
+            riskLevel,
+            approvalId,
+        });
+        const output = {
+            approvalId,
+            decision: 'approved',
+            riskLevel,
+            policyResult,
+            message: 'Auto-approved (session: dont_ask_again)',
+            waitedForRemote: false,
+        };
+        writeCheckOperation(deps, {
+            id: approvalId,
+            toolName: input.toolName,
+            toolInput: input.toolInput,
+            filePaths,
+            riskLevel,
+            decision: 'approved',
+            now,
+        });
+        writeCheckMetadata(deps, { operationId: approvalId, input, now });
+        if (deps.cloudConnector?.isConnected) {
+            const cloudAgentId = deps.cloudConnector.cloudAgentId ?? agentId;
+            deps.cloudConnector.sendProgressUpdate({
+                agentId: cloudAgentId,
+                sessionId: input.sessionId ?? cloudAgentId,
+                message: `✅ ${input.toolName} 自動核准（此工作階段不再詢問）`,
+                timestamp: now,
+                messageType: 'operation_report',
+            });
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+    }
+    // Handle ASK / WARN — 送 Cloud 審核或 fallback auto-deny
+    const { cloudConnector } = deps;
+    if (cloudConnector?.isConnected) {
+        // Cloud 已連線：送 permission_prompt 並等待 Mobile 回應
+        logger.info('hopping.check: sending to Cloud for remote approval', {
+            toolName: input.toolName,
+            approvalId,
+            finalAction: policyResult.finalAction,
+        });
+        // 先寫入 SQLite（decision 暫為 null，等待 Mobile 回應後更新）
+        writePendingCheckOperation(deps, {
+            id: approvalId,
+            toolName: input.toolName,
+            toolInput: input.toolInput,
+            filePaths,
+            riskLevel,
+            now,
+            promptType: 'approval',
+            responseType: 'binary',
+        });
+        // 寫入 metadata（含 userPrompt，僅存本地）
+        writeCheckMetadata(deps, { operationId: approvalId, input, now });
+        // 取得 risk-based timeout 設定（需在 sendPermissionPrompt 前取得，以便包含 timeoutMs）
+        const approvalConfig = await getApprovalConfigSafe(deps);
+        const timeoutMs = approvalConfig.timeouts[riskLevel];
+        // 發送 permission_prompt 到 Cloud（含 smart summary + taskContext + timeoutMs + onTimeout + toolContext，不含 userPrompt）
+        cloudConnector.sendPermissionPrompt({
+            id: approvalId,
+            agentId: agentId,
+            toolName: input.toolName,
+            riskLevel,
+            summary,
+            policyAction: policyResult.finalAction,
+            sessionId: input.sessionId,
+            timestamp: now,
+            timeoutMs,
+            onTimeout: (0, manager_1.toApprovalDecision)(approvalConfig.onTimeout[riskLevel]),
+            taskContext,
+            promptType: 'approval',
+            responseType: 'binary',
+            toolContext: {
+                description: risk_level_1.OPERATION_TYPE_DESCRIPTIONS[mappingEntry.type] ?? risk_level_1.OPERATION_TYPE_DESCRIPTIONS['unknown'],
+                parameters: input.toolInput,
+            },
+        });
+        // 通知 Mobile：操作等待審核中
+        cloudConnector.sendProgressUpdate({
+            agentId: cloudConnector.cloudAgentId ?? agentId,
+            sessionId: input.sessionId ?? agentId,
+            message: `⏳ ${input.toolName} 等待審核中...`,
+            timestamp: now,
+            messageType: 'progress',
+        });
+        // Race Mode（REQ-HUB-036）：Cloud 連線時同時啟動本地對話框，先到先贏
+        let raceAbort;
+        if (deps.localApprovalChannel?.isRaceModeEnabled) {
+            const raceHandle = deps.localApprovalChannel.startRaceDialog({
+                approvalId,
+                toolName: input.toolName,
+                riskLevel,
+                summary,
+                timeoutMs,
+            });
+            raceAbort = raceHandle.abort;
+        }
+        // 等待 ApprovalManager 回傳決策（Cloud permission_response 或 Local dialog 會 resolve）
+        // Store 更新由 CloudConnector.handlePermissionResponse 負責（非超時情況）
+        const result = await deps.approvalManager.waitForApproval(approvalId, timeoutMs);
+        // 清理 Race Mode 的 dialog（Mobile 先到時 kill dialog）
+        if (raceAbort)
+            raceAbort();
+        if (!result.timedOut) {
+            // Mobile 或 Dialog 及時回應（非超時）
+            const decision = result.approved ? 'approved' : 'denied';
+            const sourceLabel = result.source === 'local_dialog' ? 'locally via dialog' : 'remotely';
+            const output = {
+                approvalId,
+                decision,
+                riskLevel,
+                policyResult,
+                message: result.approved
+                    ? `Approved ${sourceLabel}${result.reason ? `: ${result.reason}` : ''}`
+                    : `Denied ${sourceLabel}${result.reason ? `: ${result.reason}` : ''}`,
+                waitedForRemote: result.source !== 'local_dialog',
+            };
+            // 通知 Mobile 審核決策結果
+            cloudConnector.sendProgressUpdate({
+                agentId: cloudConnector.cloudAgentId ?? agentId,
+                sessionId: input.sessionId ?? agentId,
+                message: result.approved ? `✅ ${input.toolName} 已核准` : `❌ ${input.toolName} 已拒絕`,
+                timestamp: new Date().toISOString(),
+                messageType: 'operation_report',
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+        }
+        // 超時：分層處理 — 根據 config.onTimeout[riskLevel]（TimeoutAction → TimeoutDecision 轉換）
+        const onTimeout = (0, manager_1.toApprovalDecision)(approvalConfig.onTimeout[riskLevel]);
+        const decidedAt = new Date().toISOString();
+        // 更新 SQLite（超時路徑之前 decision 為 null）
+        if (deps.store) {
+            deps.store.operations.updateDecision(approvalId, onTimeout, decidedAt);
+        }
+        logger.info('hopping.check: timeout, applying layered decision', {
+            approvalId,
+            riskLevel,
+            onTimeout,
+            timeoutMs,
+        });
+        const output = {
+            approvalId,
+            decision: onTimeout,
+            riskLevel,
+            policyResult,
+            message: buildTimeoutMessage(onTimeout, riskLevel, timeoutMs),
+            waitedForRemote: true,
+        };
+        return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+    }
+    // Cloud 未連線：Local Approval Channel（REQ-HUB-002 modified）
+    if (deps.localApprovalChannel?.isEnabled) {
+        logger.info('hopping.check: using local approval channel (Cloud disconnected)', {
+            toolName: input.toolName,
+            approvalId,
+            finalAction: policyResult.finalAction,
+        });
+        // 先寫入 SQLite（decision 暫為 null，等待用戶回應後更新）
+        writePendingCheckOperation(deps, {
+            id: approvalId,
+            toolName: input.toolName,
+            toolInput: input.toolInput,
+            filePaths,
+            riskLevel,
+            now,
+            promptType: 'approval',
+            responseType: 'binary',
+        });
+        writeCheckMetadata(deps, { operationId: approvalId, input, now });
+        const approvalConfig = await getApprovalConfigSafe(deps);
+        const timeoutMs = approvalConfig.timeouts[riskLevel];
+        const localResult = await deps.localApprovalChannel.requestApproval({
+            approvalId,
+            toolName: input.toolName,
+            riskLevel,
+            summary,
+            timeoutMs,
+        });
+        // 決定最終 decision
+        let decision;
+        let message;
+        if (localResult.decision === 'approved' || localResult.decision === 'denied') {
+            decision = localResult.decision;
+            message = buildLocalDecisionMessage(decision, localResult.source);
+        }
+        else {
+            // timeout：套用 onTimeout 分層設定（與 Cloud 路徑一致）
+            const onTimeout = (0, manager_1.toApprovalDecision)(approvalConfig.onTimeout[riskLevel]);
+            decision = onTimeout;
+            message = buildTimeoutMessage(onTimeout, riskLevel, timeoutMs);
+        }
+        const decidedAt = new Date().toISOString();
+        if (deps.store) {
+            deps.store.operations.updateDecision(approvalId, decision, decidedAt);
+        }
+        const localOutput = {
+            approvalId,
+            decision,
+            riskLevel,
+            policyResult,
+            message,
+            waitedForRemote: false,
+        };
+        return { content: [{ type: 'text', text: JSON.stringify(localOutput) }] };
+    }
+    // Fallback: Cloud 未連線 + Local Channel 未啟用 — auto-deny（安全優先）
+    logger.warn('hopping.check: auto-deny (no Cloud connection, local channel disabled)', {
+        toolName: input.toolName,
+        approvalId,
+        finalAction: policyResult.finalAction,
+    });
+    const output = {
+        approvalId,
+        decision: 'denied',
+        riskLevel,
+        policyResult,
+        message: `Denied by local policy (${policyResult.finalAction}). Remote approval not available — Cloud not connected.`,
+        waitedForRemote: false,
+    };
+    writeCheckOperation(deps, {
+        id: approvalId,
+        toolName: input.toolName,
+        toolInput: input.toolInput,
+        filePaths,
+        riskLevel,
+        decision: 'denied',
+        now,
+    });
+    writeCheckMetadata(deps, { operationId: approvalId, input, now });
+    return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+}
+// ============================================
+// hopping.report Handler
+// ============================================
+async function handleReport(input, deps) {
+    const { logger } = deps;
+    const operationId = (0, crypto_1.randomUUID)();
+    const now = new Date().toISOString();
+    if (deps.store) {
+        // Write operation record
+        deps.store.operations.insert({
+            id: operationId,
+            approvalId: null,
+            toolName: input.toolName,
+            toolParams: input.toolParams ? JSON.stringify(input.toolParams) : null,
+            filePaths: input.filePaths ? JSON.stringify(input.filePaths) : null,
+            riskLevel: null,
+            decision: null,
+            createdAt: now,
+            decidedAt: null,
+            toolUseId: null,
+        });
+        // Write metadata record
+        const reportContextTags = {};
+        if (input.context?.branch)
+            reportContextTags['branch'] = input.context.branch;
+        if (input.context?.project)
+            reportContextTags['project'] = input.context.project;
+        if (input.context?.cwd)
+            reportContextTags['cwd'] = input.context.cwd;
+        const toolResultSummary = input.result ? input.result.slice(0, 500) : null;
+        deps.store.metadata.insert({
+            operationId,
+            agentType: input.agentType ?? deps.agentType ?? 'generic_mcp',
+            sessionId: input.sessionId ?? deps.agentId ?? 'unknown',
+            durationMs: input.duration ?? null,
+            tokenUsage: null,
+            contextTags: Object.keys(reportContextTags).length > 0 ? JSON.stringify(reportContextTags) : null,
+            source: 'report',
+            resultStatus: input.success === true ? 'success' : input.success === false ? 'failure' : null,
+            toolResultSummary,
+            createdAt: now,
+        });
+        logger.info('hopping.report: operation recorded to SQLite', {
+            operationId,
+            toolName: input.toolName,
+        });
+    }
+    else {
+        // Fallback: log only (no store injected)
+        logger.info('hopping.report: operation recorded (log only, no store)', {
+            operationId,
+            toolName: input.toolName,
+            success: input.success,
+            duration: input.duration,
+            filePaths: input.filePaths,
+        });
+    }
+    if (deps.cloudConnector?.isConnected) {
+        const agentId = deps.cloudConnector.cloudAgentId ?? deps.agentId ?? 'unknown';
+        const sessionId = input.sessionId ?? agentId;
+        if (input.context?.taskCompleted) {
+            deps.cloudConnector.sendProgressUpdate({
+                agentId,
+                sessionId,
+                message: '🎉 Agent 已完成任務，目前閒置中',
+                timestamp: now,
+                messageType: 'task_completed',
+            });
+        }
+        else {
+            deps.cloudConnector.sendProgressUpdate({
+                agentId,
+                sessionId,
+                message: `📝 ${input.toolName} 操作已記錄`,
+                timestamp: now,
+                messageType: 'operation_report',
+            });
+        }
+    }
+    const output = {
+        recorded: true,
+        operationId,
+    };
+    return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+}
+// ============================================
+// hopping.status Handler
+// ============================================
+async function handleStatus(_input, deps) {
+    const { approvalManager, startTime } = deps;
+    const todayOperations = deps.store ? deps.store.operations.countToday() : 0;
+    const output = {
+        activeSessions: 0, // S1: WebSocket sessions
+        pendingApprovals: approvalManager.pendingCount,
+        todayOperations,
+        hubUptime: (Date.now() - startTime) / 1000,
+        connectedToCloud: deps.cloudConnector?.isConnected ?? false,
+        sessionMemory: deps.sessionMemory?.getAll() ?? [],
+    };
+    return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+}
+// ============================================
+// hopping.respond Handler (S2-HUB-APR-002)
+// ============================================
+async function handleRespond(input, deps) {
+    const { approvalManager, logger } = deps;
+    const { approvalId, decision, reason } = input;
+    const approved = decision === 'approved';
+    // 1. Check if still in ApprovalManager pending map
+    if (approvalManager.isPending(approvalId)) {
+        const resolved = approvalManager.resolveApproval(approvalId, approved, reason, 'local_respond');
+        if (!resolved) {
+            logger.warn('hopping.respond: isPending but resolveApproval returned false', { approvalId });
+        }
+        // Update SQLite
+        if (deps.store) {
+            deps.store.operations.updateDecision(approvalId, decision, new Date().toISOString());
+        }
+        const output = { success: true, source: 'local' };
+        logger.info('hopping.respond: resolved pending approval locally', { approvalId, decision });
+        return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+    }
+    // 2. Not in pending map — check SQLite
+    if (!deps.store) {
+        const output = { success: false, error: 'Approval request not found' };
+        return { content: [{ type: 'text', text: JSON.stringify(output) }], isError: true };
+    }
+    const record = deps.store.operations.getById(approvalId);
+    if (!record) {
+        const output = { success: false, error: 'Approval request not found' };
+        return { content: [{ type: 'text', text: JSON.stringify(output) }], isError: true };
+    }
+    // 2a. If decision is still 'pending' → update with local decision
+    if (record.decision === 'pending') {
+        deps.store.operations.updateDecision(approvalId, decision, new Date().toISOString());
+        const output = { success: true, source: 'local' };
+        logger.info('hopping.respond: updated pending record in SQLite', { approvalId, decision });
+        return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+    }
+    // 2b. Already decided (e.g. by Mobile via permission_response)
+    const output = {
+        success: true,
+        decision: record.decision,
+        source: 'remote',
+    };
+    logger.info('hopping.respond: record already decided', {
+        approvalId,
+        existingDecision: record.decision,
+    });
+    return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+}
+// ============================================
+// hopping.pair Handler
+// ============================================
+async function handlePair(input, deps) {
+    const { logger, configManager, onCloudConnectorUpdate } = deps;
+    if (!configManager || !onCloudConnectorUpdate) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: '配對不可用：ConfigManager 未初始化。請確認 Hub 版本是否正確。',
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+    // 決定 cloudUrl（優先順序：工具參數 > 依賴注入 > 預設值）
+    const cloudUrl = input.cloudUrl ?? deps.cloudUrl ?? 'http://localhost:3000';
+    // 若已連線 Cloud，先斷開（允許重新配對）
+    if (deps.cloudConnector?.isConnected) {
+        logger.warn('hopping.pair: Hub 已連線 Cloud，執行重新配對', { cloudUrl });
+        await deps.cloudConnector.disconnect();
+    }
+    // HTTP POST {cloudUrl}/api/v1/agents/pair
+    let agentId;
+    let agentName;
+    let token;
+    try {
+        const response = await fetch(`${cloudUrl}/api/v1/agents/pair`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                pairingCode: input.pairingCode,
+                clientInfo: { name: 'HopPing Hub', version: HUB_VERSION },
+            }),
+        });
+        if (!response.ok) {
+            const errText = await response.text().catch(() => '');
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: `配對失敗：HTTP ${response.status}${errText ? ` — ${errText}` : ''}`,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const raw = await response.json();
+        const parsed = schemas_1.PairApiResponseSchema.safeParse(raw);
+        if (!parsed.success) {
+            const details = parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: `配對回應格式異常：${details.join('; ')}`,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        agentId = parsed.data.agentId;
+        agentName = parsed.data.name;
+        token = parsed.data.token;
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ error: `配對請求失敗：${errMsg}` }),
+                },
+            ],
+            isError: true,
+        };
+    }
+    // 儲存 token 到本地設定（~/.hopping/config.json，chmod 0o600）
+    await configManager.saveAfterPairing(agentId, token, cloudUrl);
+    logger.info('hopping.pair: 配對成功，token 已儲存至本地設定', { agentId, cloudUrl });
+    // 建立新 CloudConnector 並連線
+    const connectorOptions = {
+        cloudUrl,
+        agentToken: token,
+        logger,
+        approvalManager: deps.approvalManager,
+        store: deps.store,
+    };
+    const newConnector = new cloud_1.CloudConnector(connectorOptions);
+    // 更新 index.ts 的 cloudConnector 參考（透過 callback）
+    onCloudConnectorUpdate(newConnector);
+    // 非阻塞連線（超時後仍以本地模式運行，socket.io 自動重連）
+    await newConnector.connect();
+    const connectedToCloud = newConnector.isConnected;
+    const output = {
+        paired: true,
+        agentId,
+        agentName,
+        connectedToCloud,
+        message: connectedToCloud
+            ? `已成功配對並連線到 Cloud（${agentName}）`
+            : `已配對成功，但 Cloud 初始連線超時。Hub 以本地模式運行，將在背景自動重連。`,
+    };
+    return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+}
+// ============================================
+// hopping.mode Handler (REQ-HUB-041)
+// ============================================
+async function handleMode(input, deps) {
+    const { logger } = deps;
+    const previousMode = askMode;
+    askMode = input.mode;
+    logger.info('hopping.mode: mode switched', { previousMode, newMode: askMode });
+    const output = {
+        mode: askMode,
+        message: askMode === 'away'
+            ? '已切換為 Away 模式。hopping.ask 的問題將送到手機，等待用戶回答。'
+            : '已切換為 Local 模式。hopping.ask 會立即回傳，請直接詢問使用者。',
+    };
+    return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+}
+// ============================================
+// hopping.ask Handler (REQ-HUB-040, mode-aware)
+// ============================================
+/** 取得 AskConfig，失敗時回傳預設值 */
+async function getAskConfigSafe(deps) {
+    if (!deps.configManager)
+        return { ...manager_1.DEFAULT_ASK_CONFIG };
+    try {
+        return await deps.configManager.getAskConfig();
+    }
+    catch {
+        return { ...manager_1.DEFAULT_ASK_CONFIG };
+    }
+}
+async function handleAsk(input, deps) {
+    const { logger } = deps;
+    const questionId = (0, crypto_1.randomUUID)();
+    const now = new Date().toISOString();
+    // ── Local 模式：立即回傳 ──
+    if (askMode === 'local') {
+        logger.info('hopping.ask: local mode, returning ask_locally', { questionId });
+        const output = {
+            questionId,
+            status: 'ask_locally',
+            answer: '',
+            respondedBy: 'local',
+            message: '目前為 Local 模式，請直接詢問使用者',
+        };
+        return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+    }
+    // ── Away 模式：送 Mobile 並阻塞等回覆 ──
+    const { cloudConnector } = deps;
+    const askConfig = await getAskConfigSafe(deps);
+    // 寫入 SQLite（promptType='question'，responseType=input.responseType）
+    if (deps.store) {
+        deps.store.operations.insert({
+            id: questionId,
+            approvalId: null,
+            toolName: 'hopping.ask',
+            toolParams: JSON.stringify({ question: input.question, responseType: input.responseType }),
+            filePaths: null,
+            riskLevel: null,
+            decision: null,
+            createdAt: now,
+            decidedAt: null,
+            toolUseId: null,
+            promptType: 'question',
+            responseType: input.responseType,
+        });
+    }
+    if (cloudConnector?.isConnected) {
+        // Cloud 已連線：送 permission_prompt（promptType='question'）
+        const agentId = cloudConnector.cloudAgentId ?? deps.agentId ?? 'unknown';
+        cloudConnector.sendPermissionPrompt({
+            id: questionId,
+            agentId,
+            toolName: 'hopping.ask',
+            riskLevel: 'low',
+            summary: input.question,
+            policyAction: 'ASK',
+            sessionId: agentId,
+            timestamp: now,
+            promptType: 'question',
+            responseType: input.responseType,
+            options: input.options,
+            placeholder: input.placeholder,
+            taskContext: input.context
+                ? {
+                    taskDescription: input.context.taskDescription,
+                    reasoning: input.context.reasoning,
+                }
+                : undefined,
+        });
+        // 通知 Mobile：問題已送出
+        cloudConnector.sendProgressUpdate({
+            agentId,
+            sessionId: agentId,
+            message: `❓ 等待用戶回答：${input.question}`,
+            timestamp: now,
+            messageType: 'progress',
+        });
+    }
+    // 等待用戶回應（askConfig timeout）
+    const timeoutMs = askConfig.timeoutEnabled ? askConfig.timeoutMs : Infinity;
+    const result = await deps.approvalManager.waitForApproval(questionId, timeoutMs);
+    if (result.timedOut) {
+        logger.info('hopping.ask: away mode timeout', { questionId });
+        // 更新 SQLite
+        if (deps.store) {
+            deps.store.operations.updateDecision(questionId, 'timeout', new Date().toISOString());
+        }
+        const output = {
+            questionId,
+            status: 'timeout',
+            answer: '',
+            respondedBy: 'local',
+            message: '用戶未回應，請自行判斷或稍後重問',
+        };
+        return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+    }
+    // 收到回應
+    logger.info('hopping.ask: away mode answered', {
+        questionId,
+        selectedOption: result.selectedOption,
+        freetext: result.freetext,
+    });
+    // 更新 SQLite
+    const decidedAt = new Date().toISOString();
+    if (deps.store) {
+        deps.store.operations.updateDecision(questionId, 'answered', decidedAt);
+        if (result.selectedOption || result.freetext || result.customText) {
+            deps.store.operations.updateResponseData(questionId, JSON.stringify({
+                selectedOption: result.selectedOption,
+                freetext: result.freetext,
+                customText: result.customText,
+            }));
+        }
+    }
+    // 決定 answer：choice → selectedOption，freetext → freetext
+    const answer = result.selectedOption ?? result.freetext ?? '';
+    const output = {
+        questionId,
+        status: 'answered',
+        answer,
+        customText: result.customText,
+        respondedBy: result.source === 'local_respond' || result.source === 'local_dialog' ? 'local' : 'mobile',
+        message: '用戶已回答',
+    };
+    return { content: [{ type: 'text', text: JSON.stringify(output) }] };
+}
+//# sourceMappingURL=tools.js.map