@zhin.js/host-http 1.0.13 → 1.0.14

package/lib/console-rest-pages.d.ts

@@ -26,6 +26,8 @@ export interface ConsoleRestCtx {
             get(name: string): unknown;
         };
     };
+    /** Distinguishes a real IM conversation with no Agent turn from a typo key. */
+    readonly isKnownConversationSession?: (sessionKey: string) => boolean | undefined | Promise<boolean | undefined>;
 }
 /** 内省数据门面 — 由 basic/cli 用 agent 包 collectIntrospection* 装配。 */
 export interface ConsoleAgentIntrospection {

package/lib/console-rest-pages.js

@@ -663,9 +663,33 @@ function registerAgentSessionRoutes(route, base, ctx) {
         try {
             const sessionId = await runtime.resolveActiveSessionId(parsed.sessionKey);
             if (!sessionId) {
-                writeJson(response, 404, {
-                    success: false,
-                    error: `未找到活跃会话：${parsed.sessionKey}`,
+                if (!isRuntimeImSessionKey(parsed.sessionKey)) {
+                    writeJson(response, 404, {
+                        success: false,
+                        error: `未找到会话：${parsed.sessionKey}`,
+                    });
+                    return;
+                }
+                const knownConversation = await ctx.isKnownConversationSession?.(parsed.sessionKey);
+                if (knownConversation === false) {
+                    writeJson(response, 404, {
+                        success: false,
+                        error: `未找到会话：${parsed.sessionKey}`,
+                    });
+                    return;
+                }
+                // 渠道会话与 Agent 会话的生命周期不同：用户可以先在 Console
+                // 选中一个真实渠道会话，而该会话尚未触发过 Agent。树查询是只读操作，
+                // 因而将这种正常状态返回为可渲染空态，而不是误报资源不存在。
+                writeJson(response, 200, {
+                    success: true,
+                    data: {
+                        state: 'not_started',
+                        sessionKey: parsed.sessionKey,
+                        sessionId: null,
+                        activeLeafMessageId: null,
+                        points: [],
+                    },
                 });
                 return;
             }
@@ -674,6 +698,7 @@ function registerAgentSessionRoutes(route, base, ctx) {
             writeJson(response, 200, {
                 success: true,
                 data: {
+                    state: 'active',
                     sessionKey: parsed.sessionKey,
                     sessionId,
                     activeLeafMessageId,
@@ -774,6 +799,16 @@ function registerAgentSessionRoutes(route, base, ctx) {
         }
     }, { summary: 'Switch agent session active leaf', tags: ['console', 'agent'] });
 }
+/** Runtime IM session keys are `<platform>:<endpoint>:<scope>:<sceneId>`. */
+function isRuntimeImSessionKey(value) {
+    const first = value.indexOf(':');
+    const second = value.indexOf(':', first + 1);
+    const third = value.indexOf(':', second + 1);
+    return first > 0
+        && second > first + 1
+        && third > second + 1
+        && third < value.length - 1;
+}
 function parseSessionAction(pathname, prefix, action) {
     if (!pathname.startsWith(prefix))
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/host-http",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "description": "Minimal HTTP and WebSocket host for Plugin Runtime (no Koa)",
   "type": "module",
   "main": "./lib/index.js",

package/src/console-rest-pages.ts

@@ -42,6 +42,10 @@ export interface ConsoleRestCtx {
     readonly started: boolean;
     readonly models: { get(name: string): unknown };
   };
+  /** Distinguishes a real IM conversation with no Agent turn from a typo key. */
+  readonly isKnownConversationSession?: (
+    sessionKey: string,
+  ) => boolean | undefined | Promise<boolean | undefined>;
 }
 
 /** 内省数据门面 — 由 basic/cli 用 agent 包 collectIntrospection* 装配。 */
@@ -864,9 +868,33 @@ function registerAgentSessionRoutes(
     try {
       const sessionId = await runtime.resolveActiveSessionId(parsed.sessionKey);
       if (!sessionId) {
-        writeJson(response, 404, {
-          success: false,
-          error: `未找到活跃会话：${parsed.sessionKey}`,
+        if (!isRuntimeImSessionKey(parsed.sessionKey)) {
+          writeJson(response, 404, {
+            success: false,
+            error: `未找到会话：${parsed.sessionKey}`,
+          });
+          return;
+        }
+        const knownConversation = await ctx.isKnownConversationSession?.(parsed.sessionKey);
+        if (knownConversation === false) {
+          writeJson(response, 404, {
+            success: false,
+            error: `未找到会话：${parsed.sessionKey}`,
+          });
+          return;
+        }
+        // 渠道会话与 Agent 会话的生命周期不同：用户可以先在 Console
+        // 选中一个真实渠道会话，而该会话尚未触发过 Agent。树查询是只读操作，
+        // 因而将这种正常状态返回为可渲染空态，而不是误报资源不存在。
+        writeJson(response, 200, {
+          success: true,
+          data: {
+            state: 'not_started',
+            sessionKey: parsed.sessionKey,
+            sessionId: null,
+            activeLeafMessageId: null,
+            points: [],
+          },
         });
         return;
       }
@@ -876,6 +904,7 @@ function registerAgentSessionRoutes(
       writeJson(response, 200, {
         success: true,
         data: {
+          state: 'active',
           sessionKey: parsed.sessionKey,
           sessionId,
           activeLeafMessageId,
@@ -975,6 +1004,17 @@ function registerAgentSessionRoutes(
   }, { summary: 'Switch agent session active leaf', tags: ['console', 'agent'] });
 }
 
+/** Runtime IM session keys are `<platform>:<endpoint>:<scope>:<sceneId>`. */
+function isRuntimeImSessionKey(value: string): boolean {
+  const first = value.indexOf(':');
+  const second = value.indexOf(':', first + 1);
+  const third = value.indexOf(':', second + 1);
+  return first > 0
+    && second > first + 1
+    && third > second + 1
+    && third < value.length - 1;
+}
+
 function parseSessionAction(
   pathname: string,
   prefix: string,