@hirey/hi-mcp-server 0.1.10 → 0.1.12

package/README.md

@@ -91,15 +91,16 @@ 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>`，不再把整段命令误当成单个可执行文件。
 
 对 OpenClaw 的普通用户本地 vendor 安装，不要显式传 `receiver_command="hi-agent-receiver"` 或 `receiver_command_argv=["hi-agent-receiver"]`。这两种旧形态都会重新把启动语义写回“按 PATH 找全局命令”。OpenClaw 要么不传 receiver 启动覆盖，让安装流默认落到 `~/.openclaw/vendor/hi/node_modules/.bin/hi-agent-receiver`，要么只传指向该本地 vendor binary 的精确 `receiver_command_argv`。
 
-如果宿主此刻就知道“当前用户会话就是 Hi 以后该回去的默认线程”，`hi_agent_install` 也可以直接带上 `host_session_key`、`default_reply_channel`、`default_reply_to`、`default_reply_account_id`、`default_reply_thread_id`、`route_missing_policy`。这组字段会同时写进 installation 的 `delivery_capabilities` 和本地 receiver config，避免出现 gateway 已经知道默认 route、但本地 receiver 还沿旧配置投递的漂移。
+对 OpenClaw 的普通用户安装，默认就应该把当前聊天绑成 Hi 以后回来的默认线程。因此 `hi_agent_install` 应直接带上 `host_session_key`、`default_reply_channel`、`default_reply_to`、`default_reply_account_id`、`default_reply_thread_id`、`route_missing_policy`。这组字段会同时写进 installation 的 `delivery_capabilities` 和本地 receiver config，避免出现 gateway 已经知道默认 route、但本地 receiver 还沿旧配置投递的漂移。如果拿不到当前聊天的 canonical `host_session_key`，OpenClaw 安装不应宣告成功，而应先把 continuity blocker 说明白。
 
 安装后如果要显式验证 continuation route，可以用 `hi_agent_test_delivery`：既可以直接传 `host_session_key` / `reply_*` 做一次显式 route probe，也可以在 installation 已设置 `default_reply_route` 时不传这些字段，让 gateway 自动沿当前 installation 的默认 route 发 probe。
 

package/dist/defaultReplyRoute.d.ts

@@ -12,4 +12,15 @@ export declare function resolveInstallDefaultReplyDeliveryContext(args: {
     defaultReplyAccountId?: unknown;
     defaultReplyThreadId?: unknown;
 }): DefaultReplyDeliveryContext | null;
+export declare function resolveInstallRouteMissingPolicy(args: {
+    hostKind: 'openclaw' | 'generic';
+    explicitRouteMissingPolicy?: unknown;
+    defaultReplyRoute?: Record<string, unknown> | null;
+}): {
+    ok: true;
+    routeMissingPolicy: string;
+} | {
+    ok: false;
+    error: 'missing_openclaw_default_reply_route';
+};
 //# sourceMappingURL=defaultReplyRoute.d.ts.map

package/dist/defaultReplyRoute.d.ts.map

@@ -1 +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"}
+{"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;AAED,wBAAgB,gCAAgC,CAAC,IAAI,EAAE;IACrD,QAAQ,EAAE,UAAU,GAAG,SAAS,CAAC;IACjC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACpD,GAAG;IACF,EAAE,EAAE,IAAI,CAAC;IACT,kBAAkB,EAAE,MAAM,CAAC;CAC5B,GAAG;IACF,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,sCAAsC,CAAC;CAC/C,CAcA"}

package/dist/defaultReplyRoute.js

@@ -26,3 +26,18 @@ export function resolveInstallDefaultReplyDeliveryContext(args) {
     }
     return null;
 }
+export function resolveInstallRouteMissingPolicy(args) {
+    const explicitRouteMissingPolicy = normalizeText(args.explicitRouteMissingPolicy);
+    // OpenClaw 安装默认就要把当前聊天绑成默认续聊入口；否则安装不该继续宣告成功。
+    if (args.hostKind === 'openclaw' && !args.defaultReplyRoute) {
+        return {
+            ok: false,
+            error: 'missing_openclaw_default_reply_route',
+        };
+    }
+    return {
+        ok: true,
+        routeMissingPolicy: explicitRouteMissingPolicy
+            || (args.defaultReplyRoute ? 'use_explicit_default_route' : ''),
+    };
+}

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,8 +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 { resolveInstallDefaultReplyDeliveryContext, } from './defaultReplyRoute.js';
+import { applyReceiverRuntimeSnapshot, receiverConfigMaterialEquals, } from './receiver-config-material.js';
+import { resolveInstallDefaultReplyDeliveryContext, resolveInstallRouteMissingPolicy, } 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',
@@ -110,8 +113,8 @@ function controlTools() {
                     host_adapter_url: { type: 'string', description: 'enable_local_receiver=true 时可选：宿主本地接收入口。OpenClaw 默认 full endpoint 为 http://127.0.0.1:18789/hooks/agent；注意 OpenClaw 配置里的 hooks.path 应保持 /hooks，而不是 /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。' },
-                    host_session_key: { type: 'string', description: '可选：把当前 OpenClaw 当前会话显式设为 default continuation route 的 canonical full session_key。只能使用结构化宿主来源返回的完整 key；不要从 openclaw status / openclaw sessions / TUI footer 这类展示文本里抄值。' },
-                    route_missing_policy: { type: 'string', description: "可选：'use_explicit_default_route'|'fail_closed'。默认在提供 host_session_key/default_reply_* 时使用 use_explicit_default_route，否则为 null。" },
+                    host_session_key: { type: 'string', description: 'OpenClaw 安装默认应传：把当前 OpenClaw 当前会话设为 default continuation route 的 canonical full session_key。只能使用结构化宿主来源返回的完整 key；不要从 openclaw status / openclaw sessions / TUI footer 这类展示文本里抄值。' },
+                    route_missing_policy: { type: 'string', description: "可选：'use_explicit_default_route'|'fail_closed'。OpenClaw 安装默认要求当前聊天 ready，因此在提供 host_session_key/default_reply_* 时应使用 use_explicit_default_route；缺失 default route 时安装会直接失败，而不是继续留下 continuity_not_ready。" },
                     default_reply_channel: { type: 'string', description: '可选：default continuation route 的 channel。' },
                     default_reply_to: { type: 'string', description: '可选：default continuation route 的宿主 target。' },
                     default_reply_account_id: { type: 'string', description: '可选：default continuation route 的 account_id。' },
@@ -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)
@@ -1206,8 +1261,19 @@ async function handleInstall(args) {
         requireOpenClawSessionKey: hostKind === 'openclaw',
         hostKind,
     });
-    const routeMissingPolicy = normalizeText(args.route_missing_policy)
-        || (defaultReplyRoute ? 'use_explicit_default_route' : '');
+    const routeMissingPolicyResolution = resolveInstallRouteMissingPolicy({
+        hostKind,
+        explicitRouteMissingPolicy: args.route_missing_policy,
+        defaultReplyRoute,
+    });
+    if (!routeMissingPolicyResolution.ok) {
+        return fail(routeMissingPolicyResolution.error, {
+            host_kind: hostKind,
+            hint: 'OpenClaw installs must bind the current chat as the default continuation route. Read the canonical full current session key from a structured OpenClaw host source and pass it as host_session_key.',
+            expected_route_missing_policy: 'use_explicit_default_route',
+        });
+    }
+    const routeMissingPolicy = routeMissingPolicyResolution.routeMissingPolicy;
     const desiredDeliveryCapabilities = buildInstallationDeliveryDeclaration({
         enableLocalReceiver,
         receiverTransport,
@@ -1242,7 +1308,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,
@@ -1252,16 +1319,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({
@@ -1297,12 +1385,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) {
@@ -1335,22 +1425,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.10",
+  "version": "0.1.12",
   "private": false,
   "type": "module",
   "main": "dist/server.js",