@hirey/hi-mcp-server 0.1.2 → 0.1.4

package/dist/server.js

@@ -1,19 +1,24 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
 import { createServer } from 'node:http';
+import path from 'node:path';
 import process from 'node:process';
 import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { normalizeAgentEndpointList, normalizeAgentInstallationDeliveryDeclaration, normalizeAgentSubscriptionList, normalizeText, } from '@hirey/hi-agent-contracts';
+import { AGENT_GATEWAY_EVENT_TOPICS, normalizeAgentEndpointList, normalizeAgentInstallationDeliveryDeclaration, normalizeAgentSubscriptionList, normalizeText, } from '@hirey/hi-agent-contracts';
 import { createHiAgentClients, exchangeHiAgentClientCredentialsToken, HiAgentGatewayClient, HiAgentPlatformClient, } from '@hirey/hi-agent-sdk';
-import { readState, updateState, } from './state.js';
+import { readState, resolveCanonicalOpenClawStateDir, resolveDefaultStateDir, resolveLegacyStateFiles, resolveStateFile, updateState, normalizeStateProfile, } from './state.js';
 const CAPABILITY_CACHE_TTL_MS = 30_000;
+const resolvedProfile = normalizeStateProfile(process.env.HI_MCP_PROFILE);
 const config = {
     host: normalizeText(process.env.HI_MCP_HOST) || '127.0.0.1',
     port: Number(process.env.HI_MCP_PORT || 8788),
-    profile: normalizeText(process.env.HI_MCP_PROFILE) || 'default',
-    stateDir: normalizeText(process.env.HI_MCP_STATE_DIR) || `${process.cwd()}/.hi-agent-state`,
+    profile: resolvedProfile,
+    stateDir: normalizeText(process.env.HI_MCP_STATE_DIR) || resolveDefaultStateDir(resolvedProfile),
     platformBaseUrl: normalizeText(process.env.HI_PLATFORM_BASE_URL),
     transport: normalizeText(process.env.HI_MCP_TRANSPORT).toLowerCase() === 'stdio' ? 'stdio' : 'http',
 };
@@ -58,6 +63,13 @@ function fail(message, detail) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function normalizeCommandArgv(input) {
+    if (!Array.isArray(input))
+        return [];
+    return input
+        .map((value) => normalizeText(value))
+        .filter(Boolean);
+}
 function controlTools() {
     // control tools 只映射 gateway/onboarding/runtime 管理面，不伪装成第二套业务 API。
     return [
@@ -71,15 +83,68 @@ function controlTools() {
                 },
             },
         },
+        {
+            name: 'hi_agent_install',
+            description: '普通用户安装第二阶段：在 hi-mcp-server 已经挂进宿主后，自动完成 register/activate、delivery 声明、默认订阅、receiver 配置与可选启动。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    display_name: { type: 'string', description: '首次安装且当前 profile 还没有 identity 时使用的人类可读名称。' },
+                    host_kind: { type: 'string', description: "可选：'openclaw'|'generic'。默认 generic。" },
+                    agent_kind: { type: 'string', description: '首次 register 时可选的 agent_kind。默认 external。' },
+                    replace_existing_state: { type: 'boolean', description: '首次 register 且本地已有 state 时，是否允许覆盖本地持久化身份。' },
+                    migrate_legacy_state: { type: 'boolean', description: '默认 true。若 canonical state 为空，则尝试一次已知 legacy state 迁移。' },
+                    enable_local_receiver: { type: 'boolean', description: '是否配置 local_receiver 作为正式事件主路径。OpenClaw 默认 true，其它宿主默认 false。' },
+                    receiver_transport: { type: 'string', description: "enable_local_receiver=true 时可选：'claim'|'stream'。默认 claim。" },
+                    receiver_start: { type: 'boolean', description: 'enable_local_receiver=true 时，是否尝试后台启动 hi-agent-receiver。默认 true。' },
+                    receiver_command: { type: 'string', description: '可选：receiver CLI 命令名。默认 hi-agent-receiver。' },
+                    receiver_command_argv: {
+                        type: 'array',
+                        description: '可选：receiver CLI 启动 argv 前缀。hi-mcp-server 会在这组 argv 后自动追加 `run --config <path>`；适合 node/npx/绝对路径场景。',
+                        items: { type: 'string' },
+                    },
+                    host_adapter_kind: { type: 'string', description: "enable_local_receiver=true 时可选：'openclaw_hooks'|'openresponses'。OpenClaw 默认 openclaw_hooks。" },
+                    host_adapter_url: { type: 'string', description: 'enable_local_receiver=true 时可选：宿主本地接收入口。OpenClaw 默认 http://127.0.0.1:18789/hooks/agent。' },
+                    host_adapter_bearer_token: { type: 'string', description: 'host_adapter_kind=openclaw_hooks 时必填：本地 hooks bearer token。' },
+                    openresponses_model: { type: 'string', description: 'host_adapter_kind=openresponses 时必填：receiver 发给本地入口使用的 model。' },
+                    subscribe_default_topics: { type: 'boolean', description: '是否自动补齐 Hi 官方默认事件订阅。默认 true。' },
+                    run_doctor: { type: 'boolean', description: '默认 true。安装完成后自动跑一次 hi_agent_doctor。' },
+                },
+            },
+        },
+        {
+            name: 'hi_agent_doctor',
+            description: '一次性检查当前安装是否已连接、已激活、事件主路径是否清晰、receiver 配置是否齐全，并在 local_receiver 场景下做真实 delivery 探测。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    include_remote: { type: 'boolean', description: '默认 true。true 时读取远端 me/installation/endpoints/subscriptions。' },
+                    probe_delivery: { type: 'boolean', description: '默认 true。当前事件主路径是 local_receiver 时，触发一次 synthetic test-delivery。' },
+                },
+            },
+        },
+        {
+            name: 'hi_agent_reset',
+            description: '清理当前 profile 的本地 Hi 安装状态；可选删除 receiver config，并尝试停止由当前 profile 记录过的 receiver 进程。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    clear_state: { type: 'boolean', description: '默认 true。是否删除当前 profile 的 hi-mcp persisted state。' },
+                    remove_receiver_config: { type: 'boolean', description: '默认 true。是否删除当前 profile 记录过的 receiver config。' },
+                    stop_receiver: { type: 'boolean', description: '默认 true。若当前 profile 记录过 receiver pid，是否尝试发 SIGTERM。' },
+                },
+            },
+        },
         {
             name: 'hi_agent_register',
             description: '按 Hi 官方 register -> token -> activate 主线创建一个新的 external agent installation，并把长期凭证持久化到本地 state。',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    agent_id: { type: 'string' },
+                    agent_id: { type: 'string', description: '可选；省略时由 gateway 正式生成 canonical ag_ id，显式传入时必须符合 ag_ 前缀规则。' },
                     display_name: { type: 'string' },
                     agent_kind: { type: 'string' },
+                    status: { type: 'string' },
                     capabilities: { type: 'object' },
                     metadata: { type: 'object' },
                     delivery_capabilities: { type: 'object' },
@@ -257,6 +322,14 @@ function isPlainObject(input) {
 function normalizeRecord(input) {
     return isPlainObject(input) ? input : {};
 }
+function normalizeBooleanFlag(value, fallback = false) {
+    if (typeof value === 'boolean')
+        return value;
+    const normalized = normalizeText(value).toLowerCase();
+    if (!normalized)
+        return fallback;
+    return normalized === 'true' || normalized === '1' || normalized === 'yes' || normalized === 'on';
+}
 async function loadWellKnown() {
     const platform = new HiAgentPlatformClient({ baseUrl: config.platformBaseUrl });
     return await platform.wellKnown();
@@ -319,6 +392,227 @@ async function createAuthorizedClients() {
         ...clients,
     };
 }
+function resolveCurrentStateFile() {
+    return resolveStateFile({
+        stateDir: config.stateDir,
+        profile: config.profile,
+    });
+}
+function normalizeHostKind(raw) {
+    return normalizeText(raw).toLowerCase() === 'openclaw' ? 'openclaw' : 'generic';
+}
+function normalizeReceiverTransport(raw) {
+    return normalizeText(raw).toLowerCase() === 'stream' ? 'stream' : 'claim';
+}
+function stateInstallSnapshot(runtime) {
+    return runtime.install || {
+        host_kind: null,
+        receiver_config_path: null,
+        receiver_pid: null,
+        receiver_last_started_at: null,
+        receiver_last_error: null,
+    };
+}
+function buildInstallRuntimeState(current, patch) {
+    return {
+        ...current,
+        install: {
+            ...stateInstallSnapshot(current),
+            ...patch,
+        },
+        updated_at: new Date().toISOString(),
+    };
+}
+async function maybeMigrateLegacyState() {
+    const targetStateFile = resolveCurrentStateFile();
+    try {
+        await fs.access(targetStateFile);
+        return { migrated: false, from: null, to: targetStateFile };
+    }
+    catch { }
+    for (const candidate of resolveLegacyStateFiles(config.profile)) {
+        if (!candidate || candidate === targetStateFile)
+            continue;
+        try {
+            const raw = await fs.readFile(candidate, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (!parsed.identity)
+                continue;
+            await fs.mkdir(path.dirname(targetStateFile), { recursive: true });
+            await fs.writeFile(targetStateFile, `${JSON.stringify(parsed, null, 2)}\n`, 'utf8');
+            return {
+                migrated: true,
+                from: candidate,
+                to: targetStateFile,
+            };
+        }
+        catch (error) {
+            if (error?.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+    }
+    return { migrated: false, from: null, to: targetStateFile };
+}
+function buildDefaultSubscriptions() {
+    return AGENT_GATEWAY_EVENT_TOPICS.map((topic) => ({
+        topic,
+        status: 'active',
+        filter: null,
+    }));
+}
+function buildInstallationDeliveryDeclaration(args) {
+    const capabilities = [];
+    if (args.enableLocalReceiver) {
+        capabilities.push({
+            kind: 'local_receiver',
+            status: 'active',
+            config: { transport: args.receiverTransport },
+        });
+    }
+    capabilities.push({
+        kind: 'claim_ack',
+        status: 'active',
+        config: { transport: 'claim' },
+    });
+    if (args.enableLocalReceiver && args.receiverTransport === 'stream') {
+        capabilities.push({
+            kind: 'pull_stream',
+            status: 'active',
+            config: { transport: 'sse' },
+        });
+    }
+    return {
+        capabilities,
+        preferred: args.enableLocalReceiver ? 'local_receiver' : 'claim_ack',
+    };
+}
+function hasActiveInstallationCapability(declaration, kind) {
+    return !!declaration?.capabilities?.some((entry) => entry.kind === kind && entry.status !== 'disabled');
+}
+function resolveReceiverConfigPath(state) {
+    const existing = normalizeText(stateInstallSnapshot(state.runtime).receiver_config_path);
+    if (existing)
+        return existing;
+    return path.join(config.stateDir, 'hi-agent-receiver.json');
+}
+function buildReceiverConfig(args) {
+    if (args.hostAdapterKind === 'openclaw_hooks' && !normalizeText(args.hostAdapterBearerToken)) {
+        throw new Error('missing_host_adapter_bearer_token');
+    }
+    if (args.hostAdapterKind === 'openresponses' && !normalizeText(args.openresponsesModel)) {
+        throw new Error('missing_openresponses_model');
+    }
+    return {
+        profile: config.profile,
+        platform_base_url: config.platformBaseUrl,
+        identity_source: {
+            kind: 'hi_mcp_profile',
+            profile: config.profile,
+            state_dir: config.stateDir,
+        },
+        runtime: {
+            last_consumed_stream_seq: 0,
+            last_claim_lease_id: null,
+            updated_at: null,
+        },
+        event_source: {
+            transport: args.receiverTransport,
+            claim_limit: 20,
+            claim_poll_interval_ms: 1500,
+            stream_reconnect_delay_ms: 2000,
+            ack_retry_after_ms: 30000,
+        },
+        host_adapter: args.hostAdapterKind === 'openresponses'
+            ? {
+                kind: 'openresponses',
+                url: args.hostAdapterUrl,
+                auth: null,
+                config: {
+                    model: normalizeText(args.openresponsesModel),
+                },
+            }
+            : {
+                kind: 'openclaw_hooks',
+                url: args.hostAdapterUrl,
+                auth: {
+                    type: 'bearer',
+                    token: normalizeText(args.hostAdapterBearerToken),
+                },
+                // OpenClaw 本地消息的展示前缀需要稳定，避免安装后又冒出第二套文案。
+                config: {
+                    name: args.hostKind === 'openclaw' ? 'Hirey Hi Agent Platform' : 'Hirey Hi',
+                    agent_id: 'main',
+                    message_prefix: '[Hi Event]',
+                },
+            },
+        _generated_by: 'hi_agent_install',
+        _generated_at: new Date().toISOString(),
+        _receiver_config_path: args.receiverConfigPath,
+    };
+}
+async function writeReceiverConfigFile(receiverConfigPath, receiverConfig) {
+    await fs.mkdir(path.dirname(receiverConfigPath), { recursive: true });
+    await fs.writeFile(receiverConfigPath, `${JSON.stringify(receiverConfig, null, 2)}\n`, 'utf8');
+}
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || Number(pid) <= 0)
+        return false;
+    try {
+        process.kill(Number(pid), 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function startDetachedReceiver(args) {
+    const [command, ...prefixArgs] = args.receiverCommandArgv;
+    if (!command)
+        throw new Error('missing_receiver_command');
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, [...prefixArgs, 'run', '--config', args.receiverConfigPath], {
+            detached: true,
+            stdio: 'ignore',
+            env: {
+                ...process.env,
+                HI_AGENT_RECEIVER_CONFIG: args.receiverConfigPath,
+            },
+        });
+        child.once('error', (error) => reject(error));
+        child.once('spawn', () => {
+            child.unref();
+            resolve(Number(child.pid || 0));
+        });
+    });
+}
+function buildDoctorSummary(args) {
+    const installState = stateInstallSnapshot(args.state.runtime);
+    const remoteInstallation = args.remote?.installation;
+    const deliveryDeclaration = remoteInstallation?.installation?.delivery_capabilities
+        || args.state.identity?.delivery_capabilities
+        || null;
+    const localReceiverEnabled = hasActiveInstallationCapability(deliveryDeclaration, 'local_receiver');
+    const deliveryProbeOk = args.deliveryProbe ? normalizeBooleanFlag(args.deliveryProbe.ok) : !localReceiverEnabled;
+    return {
+        ok: args.blockers.length === 0,
+        profile: config.profile,
+        platform_base_url: config.platformBaseUrl,
+        state_dir: config.stateDir,
+        state_file: resolveCurrentStateFile(),
+        canonical_openclaw_state_dir: resolveCanonicalOpenClawStateDir(config.profile),
+        connected: !!args.state.identity,
+        activated: !!(remoteInstallation?.installation?.activated_at || args.state.identity?.activated_at),
+        event_path: deliveryDeclaration?.preferred || (localReceiverEnabled ? 'local_receiver' : 'claim_ack'),
+        receiver_config_path: installState.receiver_config_path,
+        receiver_running: isProcessAlive(installState.receiver_pid),
+        push_ready: deliveryProbeOk,
+        blockers: args.blockers,
+        warnings: args.warnings,
+        delivery_capabilities: deliveryDeclaration,
+        delivery_probe: args.deliveryProbe,
+    };
+}
 async function handleRegister(args) {
     const current = await loadPersistedState();
     if (current.identity && args.replace_existing_state !== true) {
@@ -330,11 +624,7 @@ async function handleRegister(args) {
     }
     const { wellKnown, gateway } = await createBootstrapClients();
     const agentId = normalizeText(args.agent_id);
-    if (!agentId) {
-        return fail('missing_agent_id');
-    }
     const request = {
-        agent_id: agentId,
         display_name: normalizeText(args.display_name),
         agent_kind: normalizeText(args.agent_kind) || undefined,
         capabilities: args.capabilities,
@@ -342,6 +632,10 @@ async function handleRegister(args) {
         delivery_capabilities: normalizeAgentInstallationDeliveryDeclaration(args.delivery_capabilities),
         status: normalizeText(args.status) || undefined,
     };
+    if (agentId)
+        request.agent_id = agentId;
+    // gateway 现在会在省略 agent_id 时正式生成 canonical ag_ id；
+    // 这里保持请求与网关 contract 一致，不再人为制造一个本地占位 id。
     const registered = await gateway.register(request);
     await persistState(() => ({
         profile: config.profile,
@@ -365,11 +659,7 @@ async function handleRegister(args) {
             activated_at: registered.installation.activated_at,
             delivery_capabilities: registered.installation.delivery_capabilities,
         },
-        runtime: {
-            last_consumed_stream_seq: 0,
-            last_claim_lease_id: null,
-            updated_at: new Date().toISOString(),
-        },
+        runtime: buildInstallRuntimeState(current.runtime, {}),
     }));
     return ok({
         ok: true,
@@ -447,22 +737,353 @@ async function handleStatus(args) {
         return ok({
             ok: true,
             profile: config.profile,
+            state_dir: config.stateDir,
+            state_file: resolveCurrentStateFile(),
+            summary: {
+                connected: !!state.identity,
+                activated: !!state.identity?.activated_at,
+                receiver_config_path: stateInstallSnapshot(state.runtime).receiver_config_path,
+                receiver_running: isProcessAlive(stateInstallSnapshot(state.runtime).receiver_pid),
+            },
             state,
         });
     }
     const { gateway } = await createAuthorizedClients();
-    const me = await gateway.me();
-    const installation = await gateway.getInstallation();
+    const [me, installation, endpoints, subscriptions] = await Promise.all([
+        gateway.me(),
+        gateway.getInstallation(),
+        gateway.listEndpoints(),
+        gateway.listSubscriptions(),
+    ]);
     return ok({
         ok: true,
         profile: config.profile,
+        state_dir: config.stateDir,
+        state_file: resolveCurrentStateFile(),
+        summary: {
+            connected: !!state.identity,
+            activated: !!installation.installation?.activated_at,
+            receiver_config_path: stateInstallSnapshot(state.runtime).receiver_config_path,
+            receiver_running: isProcessAlive(stateInstallSnapshot(state.runtime).receiver_pid),
+            event_path: installation.installation?.delivery_capabilities?.preferred || null,
+        },
         state,
         remote: {
             me,
             installation,
+            endpoints,
+            subscriptions,
         },
     });
 }
+async function handleDoctor(args) {
+    const includeRemote = args.include_remote !== false;
+    const probeDelivery = args.probe_delivery !== false;
+    const state = await loadPersistedState();
+    const blockers = [];
+    const warnings = [];
+    const installState = stateInstallSnapshot(state.runtime);
+    let remote = null;
+    let deliveryProbe = null;
+    if (!state.identity) {
+        blockers.push('missing_agent_identity');
+    }
+    if (installState.host_kind === 'openclaw' && config.stateDir !== resolveCanonicalOpenClawStateDir(config.profile)) {
+        warnings.push('openclaw_state_dir_not_canonical');
+    }
+    if (includeRemote && state.identity) {
+        try {
+            const { gateway } = await createAuthorizedClients();
+            const [me, installation, endpoints, subscriptions] = await Promise.all([
+                gateway.me(),
+                gateway.getInstallation(),
+                gateway.listEndpoints(),
+                gateway.listSubscriptions(),
+            ]);
+            remote = {
+                me: me,
+                installation: installation,
+                endpoints: endpoints.endpoints,
+                subscriptions: subscriptions.subscriptions,
+            };
+            const declaration = installation.installation.delivery_capabilities || null;
+            const activeTopics = new Set((subscriptions.subscriptions || [])
+                .filter((entry) => normalizeText(entry?.status) === 'active')
+                .map((entry) => normalizeText(entry?.topic))
+                .filter(Boolean));
+            const missingTopics = AGENT_GATEWAY_EVENT_TOPICS.filter((topic) => !activeTopics.has(topic));
+            if (missingTopics.length > 0) {
+                blockers.push(`missing_default_subscriptions:${missingTopics.join(',')}`);
+            }
+            if (hasActiveInstallationCapability(declaration, 'local_receiver')) {
+                const receiverConfigPath = resolveReceiverConfigPath(state);
+                try {
+                    await fs.access(receiverConfigPath);
+                }
+                catch {
+                    blockers.push('missing_receiver_config');
+                }
+                const activePushEndpoints = (endpoints.endpoints || [])
+                    .filter((entry) => normalizeText(entry?.status) === 'active')
+                    .filter((entry) => normalizeText(entry?.profile) !== 'hi.sse.v1');
+                if (activePushEndpoints.length > 0) {
+                    warnings.push('multiple_event_paths_configured');
+                }
+                if (probeDelivery) {
+                    try {
+                        const probe = await gateway.testDelivery({
+                            text: `hi_agent_doctor:${new Date().toISOString()}`,
+                        });
+                        deliveryProbe = probe;
+                        if (!(probe.results || []).some((entry) => entry.ok)) {
+                            blockers.push('local_receiver_delivery_probe_failed');
+                        }
+                    }
+                    catch (error) {
+                        blockers.push(`local_receiver_delivery_probe_failed:${String(error?.message || error || 'unknown_error')}`);
+                    }
+                }
+                else {
+                    warnings.push('local_receiver_delivery_not_probed');
+                }
+            }
+        }
+        catch (error) {
+            blockers.push(`remote_doctor_check_failed:${String(error?.message || error || 'unknown_error')}`);
+        }
+    }
+    return ok(buildDoctorSummary({
+        state,
+        remote,
+        blockers,
+        warnings,
+        deliveryProbe,
+    }));
+}
+async function handleInstall(args) {
+    const hostKind = normalizeHostKind(args.host_kind);
+    const enableLocalReceiver = typeof args.enable_local_receiver === 'boolean'
+        ? args.enable_local_receiver
+        : hostKind === 'openclaw';
+    const receiverTransport = normalizeReceiverTransport(args.receiver_transport);
+    const subscribeDefaultTopics = args.subscribe_default_topics !== false;
+    const receiverShouldStart = enableLocalReceiver ? args.receiver_start !== false : false;
+    const receiverCommandArgv = (() => {
+        const explicitArgv = normalizeCommandArgv(args.receiver_command_argv);
+        if (explicitArgv.length > 0)
+            return explicitArgv;
+        const command = normalizeText(args.receiver_command) || 'hi-agent-receiver';
+        return [command];
+    })();
+    const hostAdapterKindRaw = normalizeText(args.host_adapter_kind).toLowerCase();
+    const hostAdapterKind = hostAdapterKindRaw === 'openresponses'
+        ? 'openresponses'
+        : 'openclaw_hooks';
+    const hostAdapterUrl = normalizeText(args.host_adapter_url)
+        || (hostKind === 'openclaw' && hostAdapterKind === 'openclaw_hooks' ? 'http://127.0.0.1:18789/hooks/agent' : '');
+    const migration = args.migrate_legacy_state !== false
+        ? await maybeMigrateLegacyState()
+        : { migrated: false, from: null, to: resolveCurrentStateFile() };
+    let state = await loadPersistedState();
+    let registerPayload = null;
+    if (!state.identity) {
+        const displayName = normalizeText(args.display_name);
+        if (!displayName) {
+            return fail('missing_display_name', {
+                profile: config.profile,
+                state_file: resolveCurrentStateFile(),
+            });
+        }
+        const registerResult = await handleRegister({
+            display_name: displayName,
+            agent_kind: normalizeText(args.agent_kind) || undefined,
+            replace_existing_state: args.replace_existing_state === true,
+        });
+        if (registerResult.isError)
+            return registerResult;
+        registerPayload = isPlainObject(registerResult.structuredContent)
+            ? registerResult.structuredContent
+            : null;
+        state = await loadPersistedState();
+    }
+    let activatePayload = null;
+    if (state.identity && !state.identity.activated_at) {
+        const activateResult = await handleActivate({});
+        if (activateResult.isError)
+            return activateResult;
+        activatePayload = isPlainObject(activateResult.structuredContent)
+            ? activateResult.structuredContent
+            : null;
+        state = await loadPersistedState();
+    }
+    const { gateway } = await createAuthorizedClients();
+    const desiredDeliveryCapabilities = buildInstallationDeliveryDeclaration({
+        enableLocalReceiver,
+        receiverTransport,
+    });
+    const updatedInstallation = await gateway.updateInstallation({
+        delivery_capabilities: desiredDeliveryCapabilities,
+    });
+    await persistState((current) => ({
+        ...current,
+        identity: current.identity
+            ? {
+                ...current.identity,
+                delivery_capabilities: updatedInstallation.installation.delivery_capabilities,
+                activated_at: updatedInstallation.installation.activated_at,
+            }
+            : current.identity,
+        runtime: buildInstallRuntimeState(current.runtime, {
+            host_kind: hostKind,
+        }),
+    }));
+    let subscriptionsPayload = null;
+    if (subscribeDefaultTopics) {
+        const subscriptions = buildDefaultSubscriptions();
+        const upserted = await gateway.upsertSubscriptions({ subscriptions });
+        subscriptionsPayload = upserted;
+    }
+    let receiverPayload = null;
+    if (enableLocalReceiver) {
+        if (!hostAdapterUrl) {
+            return fail('missing_host_adapter_url');
+        }
+        const receiverConfigPath = resolveReceiverConfigPath(await loadPersistedState());
+        const receiverConfig = buildReceiverConfig({
+            receiverConfigPath,
+            hostKind,
+            receiverTransport,
+            hostAdapterKind,
+            hostAdapterUrl,
+            hostAdapterBearerToken: normalizeText(args.host_adapter_bearer_token) || undefined,
+            openresponsesModel: normalizeText(args.openresponses_model) || undefined,
+        });
+        await writeReceiverConfigFile(receiverConfigPath, receiverConfig);
+        state = await persistState((current) => ({
+            ...current,
+            runtime: buildInstallRuntimeState(current.runtime, {
+                host_kind: hostKind,
+                receiver_config_path: receiverConfigPath,
+                receiver_last_error: null,
+            }),
+        }));
+        let receiverPid = stateInstallSnapshot(state.runtime).receiver_pid;
+        if (receiverShouldStart && !isProcessAlive(receiverPid)) {
+            try {
+                receiverPid = await startDetachedReceiver({
+                    receiverConfigPath,
+                    receiverCommandArgv,
+                });
+                state = await persistState((current) => ({
+                    ...current,
+                    runtime: buildInstallRuntimeState(current.runtime, {
+                        host_kind: hostKind,
+                        receiver_config_path: receiverConfigPath,
+                        receiver_pid: receiverPid,
+                        receiver_last_started_at: new Date().toISOString(),
+                        receiver_last_error: null,
+                    }),
+                }));
+            }
+            catch (error) {
+                state = await persistState((current) => ({
+                    ...current,
+                    runtime: buildInstallRuntimeState(current.runtime, {
+                        host_kind: hostKind,
+                        receiver_config_path: receiverConfigPath,
+                        receiver_pid: null,
+                        receiver_last_error: String(error?.message || error || 'receiver_start_failed'),
+                    }),
+                }));
+                return fail('receiver_start_failed', {
+                    receiver_config_path: receiverConfigPath,
+                    error: String(error?.message || error || 'receiver_start_failed'),
+                });
+            }
+        }
+        receiverPayload = {
+            config_path: receiverConfigPath,
+            started: receiverShouldStart,
+            receiver_pid: receiverPid || null,
+            receiver_command_argv: receiverCommandArgv,
+            transport: receiverTransport,
+            host_adapter_kind: hostAdapterKind,
+            host_adapter_url: hostAdapterUrl,
+        };
+    }
+    if (receiverShouldStart) {
+        await sleep(1500);
+    }
+    const doctor = args.run_doctor === false
+        ? null
+        : await handleDoctor({
+            include_remote: true,
+            probe_delivery: enableLocalReceiver,
+        });
+    return ok({
+        ok: true,
+        profile: config.profile,
+        state_dir: config.stateDir,
+        state_file: resolveCurrentStateFile(),
+        migrated_legacy_state: migration,
+        register: registerPayload,
+        activate: activatePayload,
+        installation: updatedInstallation,
+        subscriptions: subscriptionsPayload,
+        receiver: receiverPayload,
+        doctor: doctor?.structuredContent || null,
+    });
+}
+async function handleReset(args) {
+    const state = await loadPersistedState();
+    const installState = stateInstallSnapshot(state.runtime);
+    const stopReceiver = args.stop_receiver !== false;
+    const removeReceiverConfig = args.remove_receiver_config !== false;
+    const clearState = args.clear_state !== false;
+    let stopResult = null;
+    if (stopReceiver && isProcessAlive(installState.receiver_pid)) {
+        try {
+            process.kill(Number(installState.receiver_pid), 'SIGTERM');
+            stopResult = {
+                attempted: true,
+                pid: installState.receiver_pid,
+                signalled: true,
+            };
+        }
+        catch (error) {
+            stopResult = {
+                attempted: true,
+                pid: installState.receiver_pid,
+                signalled: false,
+                error: String(error?.message || error || 'receiver_stop_failed'),
+            };
+        }
+    }
+    const receiverConfigPath = installState.receiver_config_path || resolveReceiverConfigPath(state);
+    if (removeReceiverConfig && receiverConfigPath) {
+        await fs.rm(receiverConfigPath, { force: true });
+    }
+    if (clearState) {
+        await fs.rm(resolveCurrentStateFile(), { force: true });
+    }
+    else {
+        await persistState((current) => ({
+            ...current,
+            runtime: buildInstallRuntimeState(current.runtime, {
+                receiver_config_path: removeReceiverConfig ? null : receiverConfigPath,
+                receiver_pid: null,
+                receiver_last_error: null,
+            }),
+        }));
+    }
+    return ok({
+        ok: true,
+        profile: config.profile,
+        removed_state_file: clearState ? resolveCurrentStateFile() : null,
+        removed_receiver_config_path: removeReceiverConfig ? receiverConfigPath : null,
+        receiver_stop: stopResult,
+    });
+}
 async function handleInstallationGet() {
     const { gateway } = await createAuthorizedClients();
     const installation = await gateway.getInstallation();
@@ -645,6 +1266,12 @@ async function handleControlTool(name, args) {
     switch (name) {
         case 'hi_agent_status':
             return await handleStatus(args);
+        case 'hi_agent_install':
+            return await handleInstall(args);
+        case 'hi_agent_doctor':
+            return await handleDoctor(args);
+        case 'hi_agent_reset':
+            return await handleReset(args);
         case 'hi_agent_register':
             return await handleRegister(args);
         case 'hi_agent_connect':
@@ -695,7 +1322,7 @@ async function listTools() {
 function createMcpServer() {
     const server = new Server({
         name: 'hi-mcp-server',
-        version: '0.1.0',
+        version: '0.1.3',
     }, {
         capabilities: {
             tools: {},