@hirey/hi-mcp-server 0.1.6 → 0.1.8

package/dist/openclaw-session-key.d.ts

@@ -0,0 +1,13 @@
+export type OpenClawSessionKeyValidation = {
+    ok: true;
+    normalized: string;
+    agentId: string;
+    rest: string;
+} | {
+    ok: false;
+    reason: 'status_display_value' | 'sessions_display_value' | 'non_canonical';
+    input: string;
+};
+export declare function looksLikeOpenClawSessionKey(input: unknown): boolean;
+export declare function validateOpenClawSessionKey(input: unknown): OpenClawSessionKeyValidation | null;
+//# sourceMappingURL=openclaw-session-key.d.ts.map

package/dist/openclaw-session-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openclaw-session-key.d.ts","sourceRoot":"","sources":["../src/openclaw-session-key.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,4BAA4B,GACpC;IACE,EAAE,EAAE,IAAI,CAAC;IACT,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,sBAAsB,GAAG,wBAAwB,GAAG,eAAe,CAAC;IAC5E,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AA0CN,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQnE;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,4BAA4B,GAAG,IAAI,CAiC9F"}

package/dist/openclaw-session-key.js

@@ -0,0 +1,76 @@
+function parseCanonicalAgentSessionKey(input) {
+    const raw = input.trim().toLowerCase();
+    if (!raw) {
+        return null;
+    }
+    const parts = raw.split(':').filter(Boolean);
+    if (parts.length < 3 || parts[0] !== 'agent') {
+        return null;
+    }
+    const agentId = parts[1]?.trim();
+    const rest = parts.slice(2).join(':');
+    if (!agentId || !rest) {
+        return null;
+    }
+    return {
+        normalized: `agent:${agentId}:${rest}`,
+        agentId,
+        rest,
+    };
+}
+function looksLikeStatusDisplayValue(input) {
+    // `openclaw status` textual tables shorten long keys with a trailing Unicode ellipsis.
+    return input.includes('…');
+}
+function looksLikeSessionsDisplayValue(input) {
+    // `openclaw sessions` currently renders long keys as:
+    //   <16-char head>...<6-char tail>
+    // Keep the detector tight so we only reject the known display artifact.
+    const trimmed = input.trim();
+    return trimmed.toLowerCase().startsWith('agent:')
+        && trimmed.length === 25
+        && trimmed.slice(16, 19) === '...';
+}
+export function looksLikeOpenClawSessionKey(input) {
+    const trimmed = String(input ?? '').trim();
+    if (!trimmed) {
+        return false;
+    }
+    return trimmed.toLowerCase().startsWith('agent:')
+        || looksLikeStatusDisplayValue(trimmed)
+        || looksLikeSessionsDisplayValue(trimmed);
+}
+export function validateOpenClawSessionKey(input) {
+    const trimmed = String(input ?? '').trim();
+    if (!trimmed) {
+        return null;
+    }
+    if (looksLikeStatusDisplayValue(trimmed)) {
+        return {
+            ok: false,
+            reason: 'status_display_value',
+            input: trimmed,
+        };
+    }
+    if (looksLikeSessionsDisplayValue(trimmed)) {
+        return {
+            ok: false,
+            reason: 'sessions_display_value',
+            input: trimmed,
+        };
+    }
+    const parsed = parseCanonicalAgentSessionKey(trimmed);
+    if (!parsed) {
+        return {
+            ok: false,
+            reason: 'non_canonical',
+            input: trimmed,
+        };
+    }
+    return {
+        ok: true,
+        normalized: parsed.normalized,
+        agentId: parsed.agentId,
+        rest: parsed.rest,
+    };
+}

package/dist/receiver-command.d.ts

@@ -0,0 +1,9 @@
+export declare function resolveCanonicalOpenClawReceiverBinaryPath(homeDir?: string): string;
+export declare function buildInstallReceiverCommandArgv(args: {
+    explicitArgv: string[];
+    receiverCommand: string;
+    hostKind: 'openclaw' | 'generic';
+    enableLocalReceiver: boolean;
+    homeDir?: string;
+}): string[];
+//# sourceMappingURL=receiver-command.d.ts.map

package/dist/receiver-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receiver-command.d.ts","sourceRoot":"","sources":["../src/receiver-command.ts"],"names":[],"mappings":"AAGA,wBAAgB,0CAA0C,CAAC,OAAO,GAAE,MAAqB,GAAG,MAAM,CAEjG;AAED,wBAAgB,+BAA+B,CAAC,IAAI,EAAE;IACpD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,UAAU,GAAG,SAAS,CAAC;IACjC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,EAAE,CAQX"}

package/dist/receiver-command.js

@@ -0,0 +1,16 @@
+import os from 'node:os';
+import path from 'node:path';
+export function resolveCanonicalOpenClawReceiverBinaryPath(homeDir = os.homedir()) {
+    return path.join(homeDir, '.openclaw', 'vendor', 'hi', 'node_modules', '.bin', 'hi-agent-receiver');
+}
+export function buildInstallReceiverCommandArgv(args) {
+    if (args.explicitArgv.length > 0)
+        return args.explicitArgv;
+    if (args.receiverCommand)
+        return [args.receiverCommand];
+    // OpenClaw's public install path is user-local vendor install, not global PATH.
+    if (args.hostKind === 'openclaw' && args.enableLocalReceiver) {
+        return [resolveCanonicalOpenClawReceiverBinaryPath(args.homeDir)];
+    }
+    return ['hi-agent-receiver'];
+}

package/dist/server.js

@@ -12,6 +12,8 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextpro
 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, resolveCanonicalOpenClawStateDir, resolveDefaultStateDir, resolveLegacyStateFiles, resolveStateFile, updateState, normalizeStateProfile, } from './state.js';
+import { looksLikeOpenClawSessionKey, validateOpenClawSessionKey, } from './openclaw-session-key.js';
+import { buildInstallReceiverCommandArgv, } from './receiver-command.js';
 const CAPABILITY_CACHE_TTL_MS = 30_000;
 const resolvedProfile = normalizeStateProfile(process.env.HI_MCP_PROFILE);
 const config = {
@@ -107,7 +109,7 @@ 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 的 session_key。' },
+                    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。" },
                     default_reply_channel: { type: 'string', description: '可选：default continuation route 的 channel。' },
                     default_reply_to: { type: 'string', description: '可选：default continuation route 的宿主 target。' },
@@ -535,30 +537,91 @@ function buildInstallationDeliveryDeclaration(args) {
 function hasActiveInstallationCapability(declaration, kind) {
     return !!declaration?.capabilities?.some((entry) => entry.kind === kind && entry.status !== 'disabled');
 }
-function withInstallationIdOnReplyRoute(input, installationId) {
+function buildInvalidOpenClawSessionKeyError(reason, input) {
+    const error = new Error('invalid_openclaw_host_session_key');
+    const hint = reason === 'status_display_value'
+        ? 'Use a structured host source for the full session key; do not copy the truncated key shown by openclaw status.'
+        : reason === 'sessions_display_value'
+            ? 'Use a structured host source for the full session key; do not copy the truncated key shown by openclaw sessions.'
+            : 'Expected an OpenClaw canonical full session key shaped like agent:<agent_id>:<rest>.';
+    error.detail = {
+        reason,
+        input,
+        hint,
+    };
+    return error;
+}
+function normalizeReplyRouteSessionKey(input, options = {}) {
+    const sessionKey = normalizeText(input) || null;
+    if (!sessionKey) {
+        return null;
+    }
+    const shouldValidateAsOpenClaw = options.requireOpenClawSessionKey || looksLikeOpenClawSessionKey(sessionKey);
+    if (!shouldValidateAsOpenClaw) {
+        return sessionKey;
+    }
+    const validation = validateOpenClawSessionKey(sessionKey);
+    if (!validation) {
+        return null;
+    }
+    if (!validation.ok) {
+        throw buildInvalidOpenClawSessionKeyError(validation.reason, validation.input);
+    }
+    return validation.normalized;
+}
+function normalizeReplyRouteWithInstallationId(input, installationId, options = {}) {
     if (!isPlainObject(input))
         return null;
     const normalizedInstallationId = normalizeText(installationId) || null;
     const existingInstallationId = normalizeText(input.installation_id) || null;
-    if (!normalizedInstallationId || existingInstallationId)
+    const hasSessionKey = Object.prototype.hasOwnProperty.call(input, 'session_key')
+        || Object.prototype.hasOwnProperty.call(input, 'sessionKey');
+    const normalizedSessionKey = hasSessionKey
+        ? normalizeReplyRouteSessionKey(Object.prototype.hasOwnProperty.call(input, 'session_key')
+            ? input.session_key
+            : input.sessionKey, options)
+        : undefined;
+    if (!normalizedInstallationId && !hasSessionKey)
         return input;
-    return {
+    const output = {
         ...input,
-        installation_id: normalizedInstallationId,
     };
+    if (normalizedInstallationId && !existingInstallationId) {
+        output.installation_id = normalizedInstallationId;
+    }
+    if (hasSessionKey) {
+        if (Object.prototype.hasOwnProperty.call(output, 'session_key')) {
+            output.session_key = normalizedSessionKey;
+        }
+        else {
+            output.sessionKey = normalizedSessionKey;
+        }
+    }
+    return output;
 }
-function normalizeDeliveryCapabilitiesWithInstallationId(input, installationId) {
-    if (!isPlainObject(input)) {
-        return normalizeAgentInstallationDeliveryDeclaration(input);
+function applyNormalizedDefaultReplyRoute(input, installationId, options = {}) {
+    if (!Object.prototype.hasOwnProperty.call(input, 'default_reply_route')) {
+        return input;
     }
-    const hydrated = {
+    return {
         ...input,
-        default_reply_route: withInstallationIdOnReplyRoute(input.default_reply_route, installationId),
+        default_reply_route: normalizeReplyRouteWithInstallationId(input.default_reply_route, installationId, options),
     };
-    return normalizeAgentInstallationDeliveryDeclaration(hydrated);
 }
-function buildDefaultReplyRoute(args, installationId) {
-    const sessionKey = normalizeText(args.host_session_key) || null;
+function normalizeDeliveryCapabilitiesWithInstallationId(input, installationId) {
+    if (isPlainObject(input)) {
+        return applyNormalizedDefaultReplyRoute(input, installationId);
+    }
+    const normalized = normalizeAgentInstallationDeliveryDeclaration(input);
+    if (!isPlainObject(normalized)) {
+        return normalized;
+    }
+    return applyNormalizedDefaultReplyRoute(normalized, installationId);
+}
+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,
@@ -572,7 +635,7 @@ function buildDefaultReplyRoute(args, installationId) {
     if (!sessionKey && !hasDeliveryContext)
         return null;
     return {
-        installation_id: normalizeText(installationId) || null,
+        installation_id: normalizeText(options.installationId) || null,
         session_key: sessionKey,
         delivery_context: hasDeliveryContext ? deliveryContext : null,
     };
@@ -693,9 +756,11 @@ function buildDoctorSummary(args) {
     const defaultReplyRoute = isPlainObject(deliveryDeclaration?.default_reply_route)
         ? deliveryDeclaration.default_reply_route
         : null;
-    const continuityState = defaultReplyRoute
-        ? 'explicit_default_route_ready'
-        : (routeMissingPolicy === 'fail_closed' ? 'origin_capture_only' : 'continuity_not_ready');
+    const continuityState = defaultReplyRoute && !args.defaultReplyRouteValidation.ok
+        ? 'explicit_default_route_invalid'
+        : defaultReplyRoute
+            ? 'explicit_default_route_ready'
+            : (routeMissingPolicy === 'fail_closed' ? 'origin_capture_only' : 'continuity_not_ready');
     return {
         ok: args.blockers.length === 0,
         profile: config.profile,
@@ -715,6 +780,7 @@ function buildDoctorSummary(args) {
         delivery_capabilities: deliveryDeclaration,
         route_missing_policy: routeMissingPolicy,
         default_reply_route: defaultReplyRoute,
+        default_reply_route_validation: args.defaultReplyRouteValidation,
         delivery_probe: args.deliveryProbe,
         delivery_probe_diagnostics: args.deliveryProbeDiagnostics,
     };
@@ -806,10 +872,8 @@ async function handleRegister(args) {
         capabilities: args.capabilities,
         metadata: isPlainObject(args.metadata) ? args.metadata : null,
         // register 阶段 installation_id 由 gateway 正式生成；
-        // 这里不能先把 default_reply_route 这种需要 installation_id 的字段在 client 侧拍扁。
-        delivery_capabilities: isPlainObject(args.delivery_capabilities)
-            ? args.delivery_capabilities
-            : normalizeAgentInstallationDeliveryDeclaration(args.delivery_capabilities),
+        // 这里仍然保留 default_reply_route / route_missing_policy，但会先做 reply route 校验。
+        delivery_capabilities: normalizeDeliveryCapabilitiesWithInstallationId(args.delivery_capabilities, null),
         status: normalizeText(args.status) || undefined,
     };
     if (agentId)
@@ -963,6 +1027,11 @@ async function handleDoctor(args) {
     let remote = null;
     let deliveryProbe = null;
     let deliveryProbeDiagnostics = null;
+    let defaultReplyRouteValidation = {
+        ok: true,
+        reason: null,
+        session_key: null,
+    };
     if (!state.identity) {
         blockers.push('missing_agent_identity');
     }
@@ -985,6 +1054,35 @@ async function handleDoctor(args) {
                 subscriptions: subscriptions.subscriptions,
             };
             const declaration = installation.installation.delivery_capabilities || null;
+            const defaultReplyRoute = isPlainObject(declaration?.default_reply_route)
+                ? declaration.default_reply_route
+                : null;
+            const defaultReplyRouteSessionKey = normalizeText(defaultReplyRoute?.session_key || defaultReplyRoute?.sessionKey) || null;
+            if (defaultReplyRouteSessionKey && looksLikeOpenClawSessionKey(defaultReplyRouteSessionKey)) {
+                const validation = validateOpenClawSessionKey(defaultReplyRouteSessionKey);
+                if (validation?.ok) {
+                    defaultReplyRouteValidation = {
+                        ok: true,
+                        reason: null,
+                        session_key: validation.normalized,
+                    };
+                }
+                else if (validation) {
+                    defaultReplyRouteValidation = {
+                        ok: false,
+                        reason: validation.reason,
+                        session_key: validation.input,
+                    };
+                    blockers.push(`openclaw_default_reply_route_session_key_invalid:${validation.reason}`);
+                }
+            }
+            else {
+                defaultReplyRouteValidation = {
+                    ok: true,
+                    reason: null,
+                    session_key: defaultReplyRouteSessionKey,
+                };
+            }
             const activeTopics = new Set((subscriptions.subscriptions || [])
                 .filter((entry) => normalizeText(entry?.status) === 'active')
                 .map((entry) => normalizeText(entry?.topic))
@@ -1044,6 +1142,7 @@ async function handleDoctor(args) {
         warnings,
         deliveryProbe,
         deliveryProbeDiagnostics,
+        defaultReplyRouteValidation,
     }));
 }
 async function handleInstall(args) {
@@ -1054,13 +1153,12 @@ async function handleInstall(args) {
     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 receiverCommandArgv = buildInstallReceiverCommandArgv({
+        explicitArgv: normalizeCommandArgv(args.receiver_command_argv),
+        receiverCommand: normalizeText(args.receiver_command),
+        hostKind,
+        enableLocalReceiver,
+    });
     const hostAdapterKindRaw = normalizeText(args.host_adapter_kind).toLowerCase();
     const hostAdapterKind = hostAdapterKindRaw === 'openresponses'
         ? 'openresponses'
@@ -1103,7 +1201,10 @@ async function handleInstall(args) {
         state = await loadPersistedState();
     }
     const { gateway } = await createAuthorizedClients();
-    const defaultReplyRoute = buildDefaultReplyRoute(args, state.identity?.installation_id || null);
+    const defaultReplyRoute = buildDefaultReplyRoute(args, {
+        installationId: state.identity?.installation_id || null,
+        requireOpenClawSessionKey: hostKind === 'openclaw',
+    });
     const routeMissingPolicy = normalizeText(args.route_missing_policy)
         || (defaultReplyRoute ? 'use_explicit_default_route' : '');
     const desiredDeliveryCapabilities = buildInstallationDeliveryDeclaration({
@@ -1289,13 +1390,8 @@ async function handleInstallationUpdate(args) {
             : {}),
         ...(Object.prototype.hasOwnProperty.call(args, 'delivery_capabilities')
             // installation_update 需要保留 default_reply_route / route_missing_policy 这类扩展字段，
-            // 不能在 client 侧先被旧版 normalize 链路截断。
-            ? { delivery_capabilities: (isPlainObject(args.delivery_capabilities)
-                    ? {
-                        ...args.delivery_capabilities,
-                        default_reply_route: withInstallationIdOnReplyRoute(args.delivery_capabilities.default_reply_route, state.identity?.installation_id || null),
-                    }
-                    : normalizeDeliveryCapabilitiesWithInstallationId(args.delivery_capabilities, state.identity?.installation_id || null)) }
+            // 但 reply route 里的 session_key 仍然必须先过 canonical 校验。
+            ? { delivery_capabilities: normalizeDeliveryCapabilitiesWithInstallationId(args.delivery_capabilities, state.identity?.installation_id || null) }
             : {}),
     };
     const updated = await gateway.updateInstallation(updateRequest);
@@ -1527,7 +1623,7 @@ async function listTools() {
 function createMcpServer() {
     const server = new Server({
         name: 'hi-mcp-server',
-        version: '0.1.6',
+        version: '0.1.7',
     }, {
         capabilities: {
             tools: {},

package/package.json

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