@h-ai/serv 1.0.0-beta.17 → 1.0.0-beta.19

package/dist/index.js

@@ -1,11 +1,12 @@
-import { validateInputOrFail, resolveRequestLocale, localizeZodError } from './chunk-IQZQTAEW.js';
-import { servM, WILDCARD_ROLE, WILDCARD_PERMISSION, implement, buildHaiErrorBody } from './chunk-FEG22LCX.js';
-import process from 'process';
+import { validateInputOrFail, resolveRequestLocale, localizeZodError } from './chunk-CZ6VA2EN.js';
+import { servM, WILDCARD_ROLE, WILDCARD_PERMISSION, implement, buildHaiErrorBody } from './chunk-PLGCHDZM.js';
+import { errorMonitor } from 'events';
+import process4 from 'process';
+import { core, RequestAccessConfigSchema, TrustedProxiesSchema, HaiCommonError, err, ok } from '@h-ai/core';
 import { upgradeWebSocket, serve } from '@hono/node-server';
 import { posix } from 'path';
 import { apiContract, AUDIO_WS_PATH, AudioWsClientMessageSchema } from '@h-ai/api-contract';
 import { audit } from '@h-ai/audit';
-import { core, RequestAccessConfigSchema, TrustedProxiesSchema, HaiCommonError, err, ok } from '@h-ai/core';
 import { TRANSPORT_PLAINTEXT_RANGE, TRANSPORT_TIME_LIMITS, TRANSPORT_PROTOCOL, createTransportBodyPolicy, authenticateTransportRequest, TransportTimeError, createTransportErrorResponse, TransportBodyTooLargeError, readTransportBody, TRANSPORT_BODY_LIMITS, isValidSM2PublicKey } from '@h-ai/crypto';
 import { OpenAPIHandler } from '@orpc/openapi/fetch';
 import { Hono } from 'hono';
@@ -201,7 +202,9 @@ var AudioConnection = class {
       return;
     }
     this.queue = this.queue.then(() => task()).catch((error) => {
-      logger.debug("audio ws task failed", { error: error instanceof Error ? error.message : String(error) });
+      logger.debug("audio ws task failed", {
+        error: error instanceof Error ? error.message : String(error)
+      });
       if (!this.closed)
         this.failFromError(ws, error);
     }).finally(() => {
@@ -482,7 +485,11 @@ var AudioConnection = class {
     if (this.closed)
       return;
     logger.warn("Audio WebSocket operation failed", { error });
-    const hai = error && typeof error === "object" && "code" in error && typeof error.code === "string" && "message" in error && typeof error.message === "string" ? { code: error.code, message: error.message, httpStatus: "httpStatus" in error && typeof error.httpStatus === "number" ? error.httpStatus : 500 } : { code: HaiCommonError.INTERNAL_ERROR.code, message: "", httpStatus: 500 };
+    const hai = error && typeof error === "object" && "code" in error && typeof error.code === "string" && "message" in error && typeof error.message === "string" ? {
+      code: error.code,
+      message: error.message,
+      httpStatus: "httpStatus" in error && typeof error.httpStatus === "number" ? error.httpStatus : 500
+    } : { code: HaiCommonError.INTERNAL_ERROR.code, message: "", httpStatus: 500 };
     const safe = core.error.toPublic(hai);
     this.fail(ws, String(safe.code), safe.message);
   }
@@ -513,7 +520,9 @@ var AudioConnection = class {
     this.controller.abort();
     if (this.session && this.authorizedRequest && this.deps.onSessionEnd) {
       void Promise.resolve(this.deps.onSessionEnd(this.session, this.authorizedRequest)).catch((error) => {
-        logger.warn("audio ws session end hook failed", { error: error instanceof Error ? error.message : String(error) });
+        logger.warn("audio ws session end hook failed", {
+          error: error instanceof Error ? error.message : String(error)
+        });
       });
     }
   }
@@ -565,7 +574,9 @@ function readRemoteAddress(metadata) {
 }
 var ApiPrefixSchema = z.custom(
   (value) => typeof value === "string" && /^\/[\w.-]+(?:\/[\w.-]+)*$/.test(value) && !value.split("/").some((segment) => segment === "." || segment === ".."),
-  { error: () => servM("serv_invalidApiPrefix") }
+  {
+    error: () => servM("serv_invalidApiPrefix")
+  }
 );
 var AbsolutePathSchema = z.custom(
   (value) => typeof value === "string" && value.startsWith("/"),
@@ -573,7 +584,9 @@ var AbsolutePathSchema = z.custom(
 );
 var OpenAPIHttpConfigInputSchema = z.union([
   z.literal(false),
-  z.object({ path: AbsolutePathSchema.default("/openapi.json") })
+  z.object({
+    path: AbsolutePathSchema.default("/openapi.json")
+  })
 ]);
 var DocsHttpConfigInputSchema = z.union([
   z.literal(false),
@@ -592,7 +605,10 @@ var HealthHttpConfigInputSchema = z.union([
 var TransportRuntimeConfigInputSchema = z.union([
   z.literal(false),
   z.object({
-    maxPlaintextBytes: z.union([z.number().int().min(TRANSPORT_PLAINTEXT_RANGE.min).max(TRANSPORT_PLAINTEXT_RANGE.max), z.literal("auto")]).transform((value) => value === "auto" ? void 0 : value).optional().describe("\u666E\u901A\u4E1A\u52A1\u53CC\u5411\u660E\u6587\u4E0A\u9650\uFF1Bauto \u4E3A 1 MiB\uFF1B\u5927\u6750\u6599\u4F7F\u7528 routePlaintextBytes \u5355\u72EC\u58F0\u660E").meta({ default: "auto" }),
+    maxPlaintextBytes: z.union([
+      z.number().int().min(TRANSPORT_PLAINTEXT_RANGE.min).max(TRANSPORT_PLAINTEXT_RANGE.max),
+      z.literal("auto")
+    ]).transform((value) => value === "auto" ? void 0 : value).optional().describe("\u666E\u901A\u4E1A\u52A1\u53CC\u5411\u660E\u6587\u4E0A\u9650\uFF1Bauto \u4E3A 1 MiB\uFF1B\u5927\u6750\u6599\u4F7F\u7528 routePlaintextBytes \u5355\u72EC\u58F0\u660E").meta({ default: "auto" }),
     maxFutureSkewSeconds: z.number().int().min(0).max(TRANSPORT_TIME_LIMITS.maxFutureSkewSeconds).optional().describe("\u5141\u8BB8\u5BA2\u6237\u7AEF\u8BF7\u6C42\u65F6\u95F4\u9886\u5148\u670D\u52A1\u5668\u7684\u79D2\u6570").meta({ default: TRANSPORT_PROTOCOL.CLOCK_SKEW_MS / 1e3 }),
     maxRequestAgeSeconds: z.number().int().min(TRANSPORT_TIME_LIMITS.minRequestAgeSeconds).max(TRANSPORT_TIME_LIMITS.maxRequestAgeSeconds).optional().describe("\u8BF7\u6C42\u4ECE\u7B7E\u53D1\u8D77\u7684\u6709\u6548\u79D2\u6570").meta({ default: TRANSPORT_PROTOCOL.REQUEST_WINDOW_MS / 1e3 }),
     routePlaintextBytes: z.record(AbsolutePathSchema, z.number().int().min(TRANSPORT_PLAINTEXT_RANGE.min).max(TRANSPORT_PLAINTEXT_RANGE.max)).optional().describe("\u5B8C\u6574\u8DEF\u5F84\u6BB5\u5230\u53CC\u5411\u660E\u6587\u5B57\u8282\u4E0A\u9650\u7684\u6620\u5C04\uFF1B\u661F\u53F7\u5339\u914D\u5355\u6BB5\uFF0C\u4F9B\u9644\u4EF6\u548C\u5F52\u6863\u72EC\u7ACB\u5BB9\u91CF"),
@@ -607,7 +623,13 @@ var ServerConfigInputSchema = z.object({
 var CorsRuntimeConfigInputSchema = z.object({
   origin: z.string().optional(),
   nativeOrigins: z.string().optional(),
-  allowedHeaders: z.array(z.string()).default(["Authorization", "Content-Type", "X-Requested-With", "X-Hai-Reauthentication", "X-Hai-Terminal"]),
+  allowedHeaders: z.array(z.string()).default([
+    "Authorization",
+    "Content-Type",
+    "X-Requested-With",
+    "X-Hai-Reauthentication",
+    "X-Hai-Terminal"
+  ]),
   exposedHeaders: z.array(z.string()).default([]),
   credentials: z.boolean().default(false)
 });
@@ -632,10 +654,10 @@ var ServConfigSchema = z.object({
 }));
 function readServerEnvOverride() {
   const override = {};
-  const host = process.env.HOST;
+  const host = process4.env.HOST;
   if (host)
     override.host = host;
-  const rawPort = process.env.PORT;
+  const rawPort = process4.env.PORT;
   if (rawPort) {
     const port = Number(rawPort);
     if (Number.isInteger(port) && port >= 1 && port <= 65535)
@@ -644,7 +666,10 @@ function readServerEnvOverride() {
   return override;
 }
 function resolveServServerConfig(input = {}) {
-  return { ...ServerConfigInputSchema.parse(input), ...readServerEnvOverride() };
+  return {
+    ...ServerConfigInputSchema.parse(input),
+    ...readServerEnvOverride()
+  };
 }
 function resolveServHttpConfig(input = {}) {
   return ServHttpConfigInputSchema.parse(input);
@@ -727,7 +752,7 @@ function createRuntimeSecurityPolicy(input) {
   };
 }
 function resolveSecureRefreshCookie(defaultSecure) {
-  const override = process.env.HAI_SERV_REFRESH_COOKIE_SECURE;
+  const override = process4.env.HAI_SERV_REFRESH_COOKIE_SECURE;
   if (override === "true" || override === "false")
     return override === "true";
   return defaultSecure;
@@ -771,8 +796,14 @@ function tryNormalizeNativeOrigin(value) {
   } catch {
     return void 0;
   }
-  if (!["http:", "https:", "capacitor:", "tauri:"].includes(url.protocol) || !url.hostname || url.username || url.password || !["", "/"].includes(url.pathname) || url.search || url.hash)
+  if (![
+    "http:",
+    "https:",
+    "capacitor:",
+    "tauri:"
+  ].includes(url.protocol) || !url.hostname || url.username || url.password || !["", "/"].includes(url.pathname) || url.search || url.hash) {
     return void 0;
+  }
   return ["capacitor:", "tauri:"].includes(url.protocol) ? `${url.protocol}//${url.host}` : url.origin;
 }
 
@@ -796,7 +827,7 @@ function resolveRefreshCookieConfig(apiPrefix, config, iam) {
   return {
     cookieName: config.cookieName ?? "hai_refresh_token",
     maxAge: config.maxAge ?? 30 * 24 * 3600,
-    isSecure: config.secure ?? resolveSecureRefreshCookie(process.env.NODE_ENV === "production" || process.env.HAI_CORE_ENV === "production"),
+    isSecure: config.secure ?? resolveSecureRefreshCookie(process4.env.NODE_ENV === "production" || process4.env.HAI_CORE_ENV === "production"),
     refreshCookiePath: `${apiPrefix}${IAM_AUTH_PATHS.refresh}`,
     onRefresh,
     nativeTokenTransport: config.nativeTokenTransport
@@ -911,26 +942,46 @@ function mountRefreshCookieRoutes(app, apiPrefix, config, iam) {
       const locale = resolveRequestLocale(c.req.raw.headers);
       return c.json(buildHaiErrorBody(HaiCommonError.UNAUTHORIZED, servM("serv_errorUnauthorized", { locale })), 401);
     }
-    const result = await onRefresh(refreshToken);
-    if (!result.success) {
-      const status = result.error.httpStatus ?? 401;
+    const fail = (internal) => {
+      const safe = core.error.toPublic(internal, void 0, resolveRequestLocale(c.req.raw.headers));
+      core.logger.error("Refresh token request failed", { traceId: safe.traceId, error: internal });
       const headers = new Headers({ "Content-Type": "application/json" });
-      if (!useNativeTokenTransport)
+      if (!useNativeTokenTransport && safe.httpStatus === 401)
         headers.set("Set-Cookie", buildClearCookieHeader(cookieName, refreshCookiePath));
-      return new Response(JSON.stringify({ success: false, error: result.error }), {
-        status,
+      return new Response(JSON.stringify({ success: false, error: safe }), {
+        status: safe.httpStatus ?? 500,
         headers
       });
+    };
+    let result;
+    try {
+      result = await onRefresh(refreshToken);
+    } catch (cause) {
+      return fail({
+        ...HaiCommonError.INTERNAL_ERROR,
+        message: servM("serv_errorInternal"),
+        cause
+      });
     }
+    if (!result.success)
+      return fail(result.error);
     const tokens = result.data;
     if (useNativeTokenTransport) {
-      return new Response(JSON.stringify({ success: true, data: { tokens } }), {
+      return new Response(JSON.stringify({
+        success: true,
+        data: { tokens }
+      }), {
         status: 200,
         headers: { "Content-Type": "application/json" }
       });
     }
     const setCookie = buildSetCookieHeader(cookieName, tokens.refreshToken, refreshCookiePath, maxAge, isSecure);
-    return new Response(JSON.stringify({ success: true, data: { tokens: stripRefreshTokenFromPair(tokens) } }), {
+    return new Response(JSON.stringify({
+      success: true,
+      data: {
+        tokens: stripRefreshTokenFromPair(tokens)
+      }
+    }), {
       status: 200,
       headers: {
         "Content-Type": "application/json",
@@ -945,17 +996,41 @@ async function readRefreshTokenFromBody(request) {
 }
 
 // src/serv-cors.ts
-var DEFAULT_CORS_METHODS = ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE", "OPTIONS"];
-var DEFAULT_CORS_ALLOWED_HEADERS = ["Authorization", "Content-Type", "X-Requested-With", "X-Hai-Reauthentication", "X-Hai-Terminal"];
+var DEFAULT_CORS_METHODS = [
+  "GET",
+  "HEAD",
+  "PUT",
+  "PATCH",
+  "POST",
+  "DELETE",
+  "OPTIONS"
+];
+var DEFAULT_CORS_ALLOWED_HEADERS = [
+  "Authorization",
+  "Content-Type",
+  "X-Requested-With",
+  "X-Hai-Reauthentication",
+  "X-Hai-Terminal"
+];
 var DEFAULT_CORS_MAX_AGE = 86400;
 var corsMiddlewares = /* @__PURE__ */ new WeakSet();
 function isCorsMiddleware(middleware) {
   return corsMiddlewares.has(middleware);
 }
 function cors(config = {}) {
-  const methods = [...config.methods ?? DEFAULT_CORS_METHODS];
-  const allowedHeaders = [...config.allowedHeaders ?? DEFAULT_CORS_ALLOWED_HEADERS];
-  const exposedHeaders = [.../* @__PURE__ */ new Set(["X-Request-Id", "X-Trace-Id", ...config.exposedHeaders ?? []])];
+  const methods = [
+    ...config.methods ?? DEFAULT_CORS_METHODS
+  ];
+  const allowedHeaders = [
+    ...config.allowedHeaders ?? DEFAULT_CORS_ALLOWED_HEADERS
+  ];
+  const exposedHeaders = [
+    .../* @__PURE__ */ new Set([
+      "X-Request-Id",
+      "X-Trace-Id",
+      ...config.exposedHeaders ?? []
+    ])
+  ];
   const credentials = config.credentials ?? false;
   const maxAge = config.maxAge ?? DEFAULT_CORS_MAX_AGE;
   const originConfig = config.origin ?? "*";
@@ -1002,12 +1077,15 @@ function resolveCorsOrigin(origin, configOrigin) {
     return null;
   if (configOrigin === "*")
     return "*";
-  if (typeof configOrigin === "string")
+  if (typeof configOrigin === "string") {
     return origin === configOrigin ? origin : null;
-  if (Array.isArray(configOrigin))
+  }
+  if (Array.isArray(configOrigin)) {
     return configOrigin.includes(origin) ? origin : null;
-  if (typeof configOrigin === "function")
+  }
+  if (typeof configOrigin === "function") {
     return configOrigin(origin) ? origin : null;
+  }
   return null;
 }
 function buildCorsHeaders(options) {
@@ -1038,7 +1116,9 @@ var SCALAR_BROWSER_ENTRY_FALLBACK = "./dist/browser/standalone.js";
 var scalarScriptCache;
 async function generateSpec(contract, options = {}) {
   const generator = new OpenAPIGenerator({
-    schemaConverters: [new ZodToJsonSchemaConverter()]
+    schemaConverters: [
+      new ZodToJsonSchemaConverter()
+    ]
   });
   return generator.generate(contract, {
     info: {
@@ -1046,8 +1126,12 @@ async function generateSpec(contract, options = {}) {
       version: options.version ?? "0.1.0",
       description: options.description
     },
-    servers: options.apiPrefix ? [{ url: options.apiPrefix }] : void 0,
-    security: [{ bearerAuth: [] }],
+    servers: options.apiPrefix ? [
+      { url: options.apiPrefix }
+    ] : void 0,
+    security: [
+      { bearerAuth: [] }
+    ],
     components: {
       securitySchemes: {
         bearerAuth: { type: "http", scheme: "bearer" }
@@ -1106,8 +1190,13 @@ function createTransportMiddleware(manager, keyExchangePath, excludePaths = [],
       return handleKeyExchange(c.req.raw, manager);
     const mode = encryption?.(pathname, c.req.method);
     if (mode === "disabled") {
-      if (c.req.raw.headers.has(TRANSPORT_PROTOCOL.ENCRYPTED_HEADER) || c.req.raw.headers.has(TRANSPORT_PROTOCOL.ENVELOPE_HEADER))
-        return Response.json(err({ ...HaiCommonError.VALIDATION_ERROR, message: servM("serv_transportPlaintextRequired"), traceId: core.context.get().traceId ?? core.context.get().requestId }), { status: 400 });
+      if (c.req.raw.headers.has(TRANSPORT_PROTOCOL.ENCRYPTED_HEADER) || c.req.raw.headers.has(TRANSPORT_PROTOCOL.ENVELOPE_HEADER)) {
+        return Response.json(err({
+          ...HaiCommonError.VALIDATION_ERROR,
+          message: servM("serv_transportPlaintextRequired"),
+          traceId: core.context.get().traceId ?? core.context.get().requestId
+        }), { status: 400 });
+      }
       return next();
     }
     if (mode !== "required" && shouldExclude(pathname, excludePaths, keyExchangePath))
@@ -1212,7 +1301,12 @@ async function handleKeyExchange(request, manager) {
     if (new TextEncoder().encode(serverPublicKey).byteLength > TRANSPORT_BODY_LIMITS.publicKeyBytes)
       return jsonError(servM("serv_transportKeyExchangeFailed"), 500);
     const clientId = await manager.registerClientKey(body.clientPublicKey);
-    return new Response(JSON.stringify({ serverKeyId: manager.getServerKeyId(), serverPublicKey, clientId, maxPlaintextBytes: manager.bodyLimits.plaintextBytes }), {
+    return new Response(JSON.stringify({
+      serverKeyId: manager.getServerKeyId(),
+      serverPublicKey,
+      clientId,
+      maxPlaintextBytes: manager.bodyLimits.plaintextBytes
+    }), {
       status: 200,
       headers: { "Content-Type": "application/json; charset=utf-8" }
     });
@@ -1260,7 +1354,14 @@ function jsonError(message, status) {
 }
 
 // src/serv-app.ts
-var API_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+var API_METHODS = [
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "OPTIONS"
+];
 var audioWsServers = /* @__PURE__ */ new WeakMap();
 function createApp(options) {
   const http = resolveServHttpConfig(options.http);
@@ -1279,7 +1380,12 @@ function createApp(options) {
   });
   app.use("*", async (c, next) => {
     const requestId = resolveRequestId(c.req.header("x-request-id") ?? null);
-    await core.context.run({ requestId, userId: void 0, scopeId: void 0, jobId: void 0 }, () => core.i18n.runWithLocale(resolveRequestLocale(c.req.raw.headers), () => audit.withContext({
+    await core.context.run({
+      requestId,
+      userId: void 0,
+      scopeId: void 0,
+      jobId: void 0
+    }, () => core.i18n.runWithLocale(resolveRequestLocale(c.req.raw.headers), () => audit.withContext({
       actor: null,
       requestId,
       traceId: requestId,
@@ -1309,14 +1415,26 @@ function createApp(options) {
   });
   app.notFound((c) => c.json(buildHaiErrorBody(
     HaiCommonError.NOT_FOUND,
-    core.i18n.coreM("core_errorNotFound", { locale: resolveRequestLocale(c.req.raw.headers) })
+    core.i18n.coreM("core_errorNotFound", {
+      locale: resolveRequestLocale(c.req.raw.headers)
+    })
   ), 404));
   const iamRef = options.iam;
   const verifyToken = options.verifyToken ?? (iamRef ? (token) => iamRef.auth.verifyToken(token) : void 0);
   const contextFactory = options.createContext ?? (verifyToken ? buildAuthContextFactory(verifyToken) : parseRequestContext);
   const createContext = async (input) => {
-    const context = await contextFactory({ ...input, ip: resolveIp(input.request, input.remoteAddress) });
-    requestAuditContexts.set(input.request, { actor: context.session ? { id: context.session.userId, username: context.session.username, roles: [...context.session.roles] } : null, scopeId: context.scopeId });
+    const context = await contextFactory({
+      ...input,
+      ip: resolveIp(input.request, input.remoteAddress)
+    });
+    requestAuditContexts.set(input.request, {
+      actor: context.session ? {
+        id: context.session.userId,
+        username: context.session.username,
+        roles: [...context.session.roles]
+      } : null,
+      scopeId: context.scopeId
+    });
     return context;
   };
   let cachedSpec;
@@ -1334,7 +1452,12 @@ function createApp(options) {
       }
       return void 0;
     }
-    core.logger.info("Request access policy denied", { ruleId: decision.ruleId, reason: decision.reason, method: c.req.method, ipAddress });
+    core.logger.info("Request access policy denied", {
+      ruleId: decision.ruleId,
+      reason: decision.reason,
+      method: c.req.method,
+      ipAddress
+    });
     return c.json(buildHaiErrorBody(HaiCommonError.REQUEST_ACCESS_DENIED, core.i18n.coreM("core_requestAccessDenied")), 403);
   };
   const cors2 = options.middlewares?.filter((entry) => isCorsMiddleware(entry.middleware)) ?? [];
@@ -1423,12 +1546,21 @@ function createApp(options) {
     });
     app.get(docs.path, async (c) => {
       if (docs.requireAuth) {
-        const context = await createContext({ request: c.req.raw, remoteAddress: readRemoteAddress(c.env) });
-        if (!context.session)
-          return c.json(buildHaiErrorBody(HaiCommonError.UNAUTHORIZED, servM("serv_errorUnauthorized", { locale: resolveRequestLocale(c.req.raw.headers) })), 401);
+        const context = await createContext({
+          request: c.req.raw,
+          remoteAddress: readRemoteAddress(c.env)
+        });
+        if (!context.session) {
+          return c.json(buildHaiErrorBody(HaiCommonError.UNAUTHORIZED, servM("serv_errorUnauthorized", {
+            locale: resolveRequestLocale(c.req.raw.headers)
+          })), 401);
+        }
       }
       const specUrl = http.openapi === false ? void 0 : posix.relative(docsDirectory, http.openapi.path) || ".";
-      return c.html(createDocsPage(await getSpec(), { specUrl, scriptUrl: SCALAR_ROUTE.slice(1) }));
+      return c.html(createDocsPage(await getSpec(), {
+        specUrl,
+        scriptUrl: SCALAR_ROUTE.slice(1)
+      }));
     });
   }
   return app;
@@ -1447,7 +1579,10 @@ function mountOpenAPIRoutes(app, procedures, apiPrefix, createContext) {
   app.on([...API_METHODS], `${apiPrefix}/*`, (c, next) => handleORPC(c, next, apiPrefix, handler, createContext));
 }
 async function handleORPC(c, next, prefix, handler, createContext) {
-  const context = await createContext({ request: c.req.raw, remoteAddress: readRemoteAddress(c.env) });
+  const context = await createContext({
+    request: c.req.raw,
+    remoteAddress: readRemoteAddress(c.env)
+  });
   const { matched, response } = await core.context.run({ requestId: context.requestId, userId: context.session?.userId, scopeId: context.scopeId }, () => handler.handle(c.req.raw, { prefix, context }));
   if (!matched) {
     await next();
@@ -1477,7 +1612,10 @@ async function localizeValidationResponse(response, requestHeaders) {
     error: {
       code: HaiCommonError.VALIDATION_ERROR.code,
       traceId: core.context.get().traceId ?? core.context.get().requestId,
-      message: core.error.formatMessage({ message: servM("serv_validationFailed", { locale }), traceId: core.context.get().traceId ?? core.context.get().requestId }),
+      message: core.error.formatMessage({
+        message: servM("serv_validationFailed", { locale }),
+        traceId: core.context.get().traceId ?? core.context.get().requestId
+      }),
       httpStatus: HaiCommonError.VALIDATION_ERROR.httpStatus,
       system: HaiCommonError.VALIDATION_ERROR.system,
       module: HaiCommonError.VALIDATION_ERROR.module,
@@ -1514,6 +1652,7 @@ function listen(app, options = {}) {
   const host = options.host ?? DEFAULT_SERV_HOST;
   const port = options.port ?? DEFAULT_SERV_PORT;
   const audioServer = audioWsServers.get(app);
+  const logger3 = core.logger.child({ module: "serv", scope: "node-adapter" });
   const server = serve(
     {
       // 保留原 bindings 对象，WebSocket 升级状态由 Node adapter 在同一对象上共享。
@@ -1524,16 +1663,55 @@ function listen(app, options = {}) {
     },
     options.onListening
   );
+  let listenFailure;
+  const rememberListenFailure = (error) => {
+    listenFailure = error;
+    logger3.error("Service listener failed", { error });
+  };
+  server.on(errorMonitor, rememberListenFailure);
+  let closing;
+  let removeSignalListeners = () => {
+  };
   const handle = {
     server,
     address: { host, port },
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => {
-        if (error)
-          reject(error);
-        else resolve();
+    close: () => closing ??= (async () => {
+      removeSignalListeners();
+      const httpClosed = new Promise((resolve, reject) => {
+        server.close((error) => {
+          server.removeListener(errorMonitor, rememberListenFailure);
+          if (listenFailure) {
+            reject(listenFailure);
+            return;
+          }
+          if (error && !("code" in error && error.code === "ERR_SERVER_NOT_RUNNING" && !server.listening))
+            reject(error);
+          else resolve();
+        });
       });
-    })
+      const audioClosed = new Promise((resolve, reject) => {
+        if (!audioServer) {
+          resolve();
+          return;
+        }
+        const deadline = setTimeout(() => {
+          for (const socket of audioServer.clients)
+            socket.terminate();
+        }, 1e3);
+        audioServer.close((error) => {
+          clearTimeout(deadline);
+          if (error)
+            reject(error);
+          else resolve();
+        });
+        for (const socket of audioServer.clients)
+          socket.close(1001, "Server shutting down");
+      });
+      const results = await Promise.allSettled([httpClosed, audioClosed]);
+      const errors = results.filter((result) => result.status === "rejected").map((result) => result.reason);
+      if (errors.length)
+        throw new AggregateError(errors, "Service listener shutdown failed");
+    })()
   };
   if (options.onClose) {
     const onClose = options.onClose;
@@ -1544,15 +1722,24 @@ function listen(app, options = {}) {
       shuttingDown = true;
       try {
         await handle.close();
-      } catch {
+      } catch (error) {
+        logger3.error("Service listener shutdown failed", { error });
       }
       try {
         await onClose();
-      } catch {
+      } catch (error) {
+        logger3.error("Service resource shutdown failed", { error });
       }
     };
-    process.once("SIGINT", () => void shutdown());
-    process.once("SIGTERM", () => void shutdown());
+    const onSignal = () => {
+      void shutdown();
+    };
+    process4.once("SIGINT", onSignal);
+    process4.once("SIGTERM", onSignal);
+    removeSignalListeners = () => {
+      process4.removeListener("SIGINT", onSignal);
+      process4.removeListener("SIGTERM", onSignal);
+    };
   }
   return handle;
 }