@hirey/hi-mcp-server 0.1.9 → 0.1.11

package/README.md

@@ -91,9 +91,10 @@ npm install -g @hirey/hi-mcp-server
 1. 用宿主把 `hi-mcp-server` 作为 `stdio` MCP server 挂上
 2. 优先执行 `hi_agent_install`，而不是让用户手工走 `register -> connect -> activate`
 3. `hi_agent_install` 会自动完成 register / activate、delivery capability 声明、默认订阅，以及在 OpenClaw 场景下的 receiver 配置
-4. `agent_id` 可以省略；省略时由 gateway 正式生成 canonical `ag_...`，不需要用户手写
-5. 完成后执行 `hi_agent_doctor`
-6. 如果要 clean reinstall，先执行 `hi_agent_reset`
+4. 当 receiver 的物料配置（例如 hooks token、adapter URL、transport、default reply route）发生变化时，`hi_agent_install` 会先停止当前 profile 记录的 receiver，再写入新配置并按需要重新启动；如果配置没变，则保留现有 runtime cursor，不重置消费进度
+5. `agent_id` 可以省略；省略时由 gateway 正式生成 canonical `ag_...`，不需要用户手写
+6. 完成后执行 `hi_agent_doctor`
+7. 如果要 clean reinstall，先执行 `hi_agent_reset`；`hi_agent_reset` 现在会等待当前 profile 记录的 receiver 真实退出，再删除本地 state / receiver config，避免立刻重装时旧进程把旧配置写回去
 
 如果宿主不能直接执行裸命令 `hi-agent-receiver`，而是需要 `node /path/to/dist/server.js`、`npx ...` 或其它显式 argv 前缀，`hi_agent_install` 现在也支持把 receiver 启动入口写成 `receiver_command_argv` 数组；`hi-mcp-server` 会在这组 argv 后自动追加 `run --config <path>`，不再把整段命令误当成单个可执行文件。
 

package/dist/defaultReplyRoute.d.ts

@@ -0,0 +1,15 @@
+export type DefaultReplyDeliveryContext = {
+    channel: string | null;
+    to: string | null;
+    account_id: string | null;
+    thread_id: string | null;
+};
+export declare function resolveInstallDefaultReplyDeliveryContext(args: {
+    hostKind: 'openclaw' | 'generic';
+    hasSessionKey: boolean;
+    defaultReplyChannel?: unknown;
+    defaultReplyTo?: unknown;
+    defaultReplyAccountId?: unknown;
+    defaultReplyThreadId?: unknown;
+}): DefaultReplyDeliveryContext | null;
+//# sourceMappingURL=defaultReplyRoute.d.ts.map

package/dist/defaultReplyRoute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaultReplyRoute.d.ts","sourceRoot":"","sources":["../src/defaultReplyRoute.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,2BAA2B,GAAG;IACxC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAAC;AAEF,wBAAgB,yCAAyC,CAAC,IAAI,EAAE;IAC9D,QAAQ,EAAE,UAAU,GAAG,SAAS,CAAC;IACjC,aAAa,EAAE,OAAO,CAAC;IACvB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,GAAG,2BAA2B,GAAG,IAAI,CAyBrC"}

package/dist/defaultReplyRoute.js

@@ -0,0 +1,28 @@
+function normalizeText(input) {
+    return String(input || '').trim();
+}
+export function resolveInstallDefaultReplyDeliveryContext(args) {
+    const explicit = {
+        channel: normalizeText(args.defaultReplyChannel) || null,
+        to: normalizeText(args.defaultReplyTo) || null,
+        account_id: normalizeText(args.defaultReplyAccountId) || null,
+        thread_id: normalizeText(args.defaultReplyThreadId) || null,
+    };
+    const hasExplicit = !!(explicit.channel
+        || explicit.to
+        || explicit.account_id
+        || explicit.thread_id);
+    if (hasExplicit)
+        return explicit;
+    // OpenClaw hooks continuation accepts `last|imessage`; when we already have the
+    // canonical session key, `last` is the canonical "same chat" lane.
+    if (args.hostKind === 'openclaw' && args.hasSessionKey) {
+        return {
+            channel: 'last',
+            to: null,
+            account_id: null,
+            thread_id: null,
+        };
+    }
+    return null;
+}

package/dist/receiver-config-material.d.ts

@@ -0,0 +1,4 @@
+export declare function receiverConfigMaterialSnapshot(raw: unknown): Record<string, unknown> | null;
+export declare function receiverConfigMaterialEquals(left: unknown, right: unknown): boolean;
+export declare function applyReceiverRuntimeSnapshot(nextConfig: Record<string, unknown>, existingConfig: unknown): Record<string, unknown>;
+//# sourceMappingURL=receiver-config-material.d.ts.map

package/dist/receiver-config-material.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receiver-config-material.d.ts","sourceRoot":"","sources":["../src/receiver-config-material.ts"],"names":[],"mappings":"AAcA,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAQ3F;AAED,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAEnF;AAED,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,cAAc,EAAE,OAAO,GACtB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBzB"}

package/dist/receiver-config-material.js

@@ -0,0 +1,47 @@
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function canonicalizeJson(value) {
+    if (Array.isArray(value))
+        return value.map((entry) => canonicalizeJson(entry));
+    if (!isPlainObject(value))
+        return value;
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+        out[key] = canonicalizeJson(value[key]);
+    }
+    return out;
+}
+export function receiverConfigMaterialSnapshot(raw) {
+    if (!isPlainObject(raw))
+        return null;
+    const snapshot = JSON.parse(JSON.stringify(raw));
+    delete snapshot.runtime;
+    delete snapshot._generated_at;
+    delete snapshot._generated_by;
+    delete snapshot._receiver_config_path;
+    return canonicalizeJson(snapshot);
+}
+export function receiverConfigMaterialEquals(left, right) {
+    return JSON.stringify(receiverConfigMaterialSnapshot(left)) === JSON.stringify(receiverConfigMaterialSnapshot(right));
+}
+export function applyReceiverRuntimeSnapshot(nextConfig, existingConfig) {
+    if (!isPlainObject(existingConfig) || !isPlainObject(existingConfig.runtime))
+        return nextConfig;
+    const runtime = existingConfig.runtime;
+    return {
+        ...nextConfig,
+        // 安装修复时保留已消费 cursor，避免仅因重写物料配置就把 receiver 从头回放。
+        runtime: {
+            last_consumed_stream_seq: Number.isFinite(Number(runtime.last_consumed_stream_seq))
+                ? Math.max(0, Number(runtime.last_consumed_stream_seq))
+                : 0,
+            last_claim_lease_id: typeof runtime.last_claim_lease_id === 'string'
+                ? runtime.last_claim_lease_id
+                : null,
+            updated_at: typeof runtime.updated_at === 'string'
+                ? runtime.updated_at
+                : null,
+        },
+    };
+}

package/dist/server.js

@@ -14,7 +14,11 @@ import { createHiAgentClients, exchangeHiAgentClientCredentialsToken, HiAgentGat
 import { readState, resolveCanonicalOpenClawStateDir, resolveDefaultStateDir, resolveLegacyStateFiles, resolveStateFile, updateState, normalizeStateProfile, } from './state.js';
 import { looksLikeOpenClawSessionKey, validateOpenClawSessionKey, } from './openclaw-session-key.js';
 import { buildInstallReceiverCommandArgv, } from './receiver-command.js';
+import { applyReceiverRuntimeSnapshot, receiverConfigMaterialEquals, } from './receiver-config-material.js';
+import { resolveInstallDefaultReplyDeliveryContext, } from './defaultReplyRoute.js';
 const CAPABILITY_CACHE_TTL_MS = 30_000;
+const RECEIVER_STOP_TIMEOUT_MS = 3_000;
+const RECEIVER_STOP_POLL_MS = 100;
 const resolvedProfile = normalizeStateProfile(process.env.HI_MCP_PROFILE);
 const config = {
     host: normalizeText(process.env.HI_MCP_HOST) || '127.0.0.1',
@@ -622,16 +626,15 @@ function buildDefaultReplyRoute(args, options = {}) {
     const sessionKey = normalizeReplyRouteSessionKey(args.host_session_key, {
         requireOpenClawSessionKey: options.requireOpenClawSessionKey,
     });
-    const deliveryContext = {
-        channel: normalizeText(args.default_reply_channel) || null,
-        to: normalizeText(args.default_reply_to) || null,
-        account_id: normalizeText(args.default_reply_account_id) || null,
-        thread_id: normalizeText(args.default_reply_thread_id) || null,
-    };
-    const hasDeliveryContext = !!(deliveryContext.channel
-        || deliveryContext.to
-        || deliveryContext.account_id
-        || deliveryContext.thread_id);
+    const deliveryContext = resolveInstallDefaultReplyDeliveryContext({
+        hostKind: options.hostKind === 'openclaw' ? 'openclaw' : 'generic',
+        hasSessionKey: !!sessionKey,
+        defaultReplyChannel: args.default_reply_channel,
+        defaultReplyTo: args.default_reply_to,
+        defaultReplyAccountId: args.default_reply_account_id,
+        defaultReplyThreadId: args.default_reply_thread_id,
+    });
+    const hasDeliveryContext = !!deliveryContext;
     if (!sessionKey && !hasDeliveryContext)
         return null;
     return {
@@ -724,6 +727,58 @@ function isProcessAlive(pid) {
         return false;
     }
 }
+async function waitForProcessExit(pid, timeoutMs = RECEIVER_STOP_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isProcessAlive(pid))
+            return true;
+        await sleep(RECEIVER_STOP_POLL_MS);
+    }
+    return !isProcessAlive(pid);
+}
+async function stopTrackedReceiverProcess(pidRaw) {
+    const pid = Number(pidRaw || 0);
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return {
+            attempted: false,
+            pid: null,
+            signal: null,
+            exited: true,
+            timeout_ms: RECEIVER_STOP_TIMEOUT_MS,
+        };
+    }
+    if (!isProcessAlive(pid)) {
+        return {
+            attempted: true,
+            pid,
+            signal: null,
+            exited: true,
+            timeout_ms: RECEIVER_STOP_TIMEOUT_MS,
+        };
+    }
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch (error) {
+        if (error?.code === 'ESRCH') {
+            return {
+                attempted: true,
+                pid,
+                signal: 'SIGTERM',
+                exited: true,
+                timeout_ms: RECEIVER_STOP_TIMEOUT_MS,
+            };
+        }
+        throw error;
+    }
+    return {
+        attempted: true,
+        pid,
+        signal: 'SIGTERM',
+        exited: await waitForProcessExit(pid),
+        timeout_ms: RECEIVER_STOP_TIMEOUT_MS,
+    };
+}
 async function startDetachedReceiver(args) {
     const [command, ...prefixArgs] = args.receiverCommandArgv;
     if (!command)
@@ -1204,6 +1259,7 @@ async function handleInstall(args) {
     const defaultReplyRoute = buildDefaultReplyRoute(args, {
         installationId: state.identity?.installation_id || null,
         requireOpenClawSessionKey: hostKind === 'openclaw',
+        hostKind,
     });
     const routeMissingPolicy = normalizeText(args.route_missing_policy)
         || (defaultReplyRoute ? 'use_explicit_default_route' : '');
@@ -1241,7 +1297,8 @@ async function handleInstall(args) {
             return fail('missing_host_adapter_url');
         }
         const receiverConfigPath = resolveReceiverConfigPath(await loadPersistedState());
-        const receiverConfig = buildReceiverConfig({
+        let existingReceiverConfig = await readReceiverConfigSnapshot(receiverConfigPath);
+        const desiredReceiverConfig = buildReceiverConfig({
             receiverConfigPath,
             hostKind,
             receiverTransport,
@@ -1251,16 +1308,37 @@ async function handleInstall(args) {
             openresponsesModel: normalizeText(args.openresponses_model) || undefined,
             defaultReplyRoute,
         });
-        await writeReceiverConfigFile(receiverConfigPath, receiverConfig);
+        const receiverConfigChanged = !receiverConfigMaterialEquals(existingReceiverConfig, desiredReceiverConfig);
+        let receiverPid = stateInstallSnapshot(state.runtime).receiver_pid;
+        let receiverStop = null;
+        if (receiverConfigChanged && isProcessAlive(receiverPid)) {
+            // 先停 tracked receiver，避免旧进程继续拿旧 token 投递，并把旧物料配置再写回磁盘。
+            receiverStop = await stopTrackedReceiverProcess(receiverPid);
+            if (!normalizeBooleanFlag(receiverStop?.exited)) {
+                return fail('receiver_stop_timeout', {
+                    receiver_config_path: receiverConfigPath,
+                    receiver_pid: receiverPid,
+                    receiver_stop: receiverStop,
+                });
+            }
+            receiverPid = null;
+            // 停掉 tracked receiver 后再读一次磁盘，尽量保留它退出前最后一次写下的 runtime cursor。
+            existingReceiverConfig = await readReceiverConfigSnapshot(receiverConfigPath);
+        }
+        if (receiverConfigChanged) {
+            const receiverConfig = applyReceiverRuntimeSnapshot(desiredReceiverConfig, existingReceiverConfig);
+            await writeReceiverConfigFile(receiverConfigPath, receiverConfig);
+        }
         state = await persistState((current) => ({
             ...current,
             runtime: buildInstallRuntimeState(current.runtime, {
                 host_kind: hostKind,
                 receiver_config_path: receiverConfigPath,
+                receiver_pid: isProcessAlive(receiverPid) ? receiverPid : null,
                 receiver_last_error: null,
             }),
         }));
-        let receiverPid = stateInstallSnapshot(state.runtime).receiver_pid;
+        receiverPid = stateInstallSnapshot(state.runtime).receiver_pid;
         if (receiverShouldStart && !isProcessAlive(receiverPid)) {
             try {
                 receiverPid = await startDetachedReceiver({
@@ -1296,12 +1374,14 @@ async function handleInstall(args) {
         }
         receiverPayload = {
             config_path: receiverConfigPath,
+            config_changed: receiverConfigChanged,
             started: receiverShouldStart,
             receiver_pid: receiverPid || null,
             receiver_command_argv: receiverCommandArgv,
             transport: receiverTransport,
             host_adapter_kind: hostAdapterKind,
             host_adapter_url: hostAdapterUrl,
+            ...(receiverStop ? { receiver_stop: receiverStop } : {}),
         };
     }
     if (receiverShouldStart) {
@@ -1334,22 +1414,21 @@ async function handleReset(args) {
     const removeReceiverConfig = args.remove_receiver_config !== false;
     const clearState = args.clear_state !== false;
     let stopResult = null;
-    if (stopReceiver && isProcessAlive(installState.receiver_pid)) {
+    if (stopReceiver && Number.isInteger(installState.receiver_pid) && Number(installState.receiver_pid) > 0) {
         try {
-            process.kill(Number(installState.receiver_pid), 'SIGTERM');
-            stopResult = {
-                attempted: true,
-                pid: installState.receiver_pid,
-                signalled: true,
-            };
+            stopResult = await stopTrackedReceiverProcess(installState.receiver_pid);
         }
         catch (error) {
-            stopResult = {
-                attempted: true,
+            return fail('receiver_stop_failed', {
                 pid: installState.receiver_pid,
-                signalled: false,
                 error: String(error?.message || error || 'receiver_stop_failed'),
-            };
+            });
+        }
+        if (!normalizeBooleanFlag(stopResult?.exited)) {
+            return fail('receiver_stop_timeout', {
+                pid: installState.receiver_pid,
+                receiver_stop: stopResult,
+            });
         }
     }
     const receiverConfigPath = installState.receiver_config_path || resolveReceiverConfigPath(state);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hirey/hi-mcp-server",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "private": false,
   "type": "module",
   "main": "dist/server.js",