@cloudbase/agent-server 0.0.15 → 0.0.18

package/dist/index.d.ts

@@ -10,6 +10,14 @@ import { Repeater } from '@repeaterjs/repeater';
 import * as _whatwg_node_server from '@whatwg-node/server';
 import { OpenAI } from 'openai';
 
+/**
+ * Type-only reference to ObservabilityConfig for documentation purposes.
+ * The actual type is: ObservabilityConfig | ObservabilityConfig[]
+ *
+ * At runtime, this accepts any value matching the ObservabilityConfig interface
+ * from @cloudbase/agent-observability/server package (if installed).
+ */
+type ObservabilityConfigOrArray = any;
 /**
  * Context passed to the agent factory function.
  * Contains request information for per-request agent configuration.
@@ -53,16 +61,49 @@ interface ICreateServer {
      * createExpressServer({ createAgent, logger: pino({ level: 'info' }) });
      */
     logger?: Logger;
+    /**
+     * Observability configuration for trace exporters.
+     *
+     * Requires @cloudbase/agent-observability package to be installed.
+     * If the package is not installed, this option is silently ignored.
+     *
+     * Type reference: ObservabilityConfig | ObservabilityConfig[] from @cloudbase/agent-observability/server
+     *
+     * @example
+     * // Console exporter (from env AUTO_TRACES_STDOUT)
+     * createExpressServer({ createAgent, observability: { type: 'console' } });
+     *
+     * // OTLP exporter (Langfuse, Jaeger, etc.)
+     * createExpressServer({
+     *   createAgent,
+     *   observability: {
+     *     type: 'otlp',
+     *     url: 'https://cloud.langfuse.com/api/public/otlp/v1/traces',
+     *     headers: { 'Authorization': 'Basic xxx' }
+     *   }
+     * });
+     *
+     * // Multiple exporters
+     * createExpressServer({
+     *   createAgent,
+     *   observability: [
+     *     { type: 'console' },
+     *     { type: 'otlp', url: 'http://localhost:4318/v1/traces' }
+     *   ]
+     * });
+     */
+    observability?: ObservabilityConfigOrArray;
 }
 interface IRun extends ICreateServer {
     port?: number | string;
 }
 interface ICreateExpressRoutes extends Omit<ICreateServer, "cors"> {
     express: Express;
+    observability?: ICreateServer["observability"];
 }
 declare function run(props: IRun): void;
 declare function createExpressServer(props: ICreateServer): Express;
-declare function createExpressRoutes({ createAgent, basePath: _basePath, express, useAGUI: _useAGUI, aguiOptions, logger: _logger, }: ICreateExpressRoutes): expressLib.Express;
+declare function createExpressRoutes({ createAgent, basePath: _basePath, express, useAGUI: _useAGUI, aguiOptions, logger: _logger, observability, }: ICreateExpressRoutes): expressLib.Express;
 interface AGUIOptions {
     runtimeOptions?: Partial<CopilotRuntimeOptions>;
     endpointOptions?: Partial<CreateCopilotRuntimeServerOptions>;

package/dist/index.js

@@ -389,12 +389,52 @@ var ErrorCode = {
 };
 
 // src/agui/sendMessageAGUI/server.ts
+var startObservation;
+var setupObservability;
+var processTraceContextFromHeaders;
+var observabilityLoadingPromise = null;
+async function loadObservability() {
+  if (startObservation) {
+    return true;
+  }
+  if (observabilityLoadingPromise) {
+    return observabilityLoadingPromise;
+  }
+  observabilityLoadingPromise = (async () => {
+    try {
+      const obs = await import("@cloudbase/agent-observability");
+      const obsServer = await import("@cloudbase/agent-observability/server");
+      startObservation = obs.startObservation;
+      processTraceContextFromHeaders = obs.processTraceContextFromHeaders;
+      setupObservability = obsServer.setupObservability;
+      return true;
+    } catch (e) {
+      return false;
+    }
+  })();
+  return observabilityLoadingPromise;
+}
+async function ensureObservabilityReady() {
+  if (!setupObservability) return false;
+  try {
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => reject(new Error("Observability setup timeout")), 2e3);
+    });
+    await Promise.race([
+      setupObservability(),
+      timeoutPromise
+    ]);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
 function createServerAdapter2(createAgent, options) {
   var _a;
   const { logger: parentLogger = import_agent_shared2.noopLogger } = options ?? {};
   const adapterLogger = ((_a = parentLogger.child) == null ? void 0 : _a.call(parentLogger, { component: "sendMessageAGUI" })) ?? parentLogger;
   return (0, import_server3.createServerAdapter)(async (request) => {
-    var _a2, _b, _c, _d, _e, _f, _g, _h;
+    var _a2, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n;
     const requestId = getOrGenerateRequestId(request.headers, "agui");
     const logger = ((_a2 = adapterLogger.child) == null ? void 0 : _a2.call(adapterLogger, { requestId })) ?? adapterLogger;
     (_b = logger.info) == null ? void 0 : _b.call(logger, "Request received");
@@ -474,11 +514,71 @@ function createServerAdapter2(createAgent, options) {
         }
       );
     }
-    const events = handler2(
-      inputRes.result,
-      createAgentRes.result.agent
-    );
-    let heartbeat;
+    const hasObservability = await loadObservability();
+    let serverSpan = null;
+    let serverContextData = null;
+    if (hasObservability && startObservation) {
+      try {
+        const isReady = await ensureObservabilityReady();
+        if (isReady) {
+          const spanAttributes = {
+            "http.method": request.method,
+            "http.url": request.url,
+            "http.host": request.headers.get("host") || "unknown",
+            "http.user_agent": request.headers.get("user-agent") || "unknown",
+            "agui.thread_id": inputRes.result.threadId,
+            "agui.run_id": inputRes.result.runId,
+            "agui.request_id": requestId
+          };
+          if (processTraceContextFromHeaders) {
+            try {
+              const traceContext = processTraceContextFromHeaders(
+                request.headers,
+                logger
+              );
+              if (traceContext.isInherited) {
+                Object.assign(spanAttributes, traceContext.spanAttributes);
+              }
+              serverSpan = startObservation(
+                "AG-UI.Server",
+                spanAttributes,
+                {
+                  asType: "chain",
+                  links: traceContext.links.length > 0 ? traceContext.links : void 0
+                }
+              );
+            } catch (e) {
+              (_i = logger.debug) == null ? void 0 : _i.call(logger, "Failed to process external trace context:", e);
+              serverSpan = startObservation(
+                "AG-UI.Server",
+                spanAttributes,
+                { asType: "chain" }
+              );
+            }
+          } else {
+            serverSpan = startObservation(
+              "AG-UI.Server",
+              spanAttributes,
+              { asType: "chain" }
+            );
+          }
+          const spanContext = (_k = (_j = serverSpan == null ? void 0 : serverSpan.otelSpan) == null ? void 0 : _j.spanContext) == null ? void 0 : _k.call(_j);
+          if ((spanContext == null ? void 0 : spanContext.traceId) && (spanContext == null ? void 0 : spanContext.spanId)) {
+            serverContextData = {
+              traceId: spanContext.traceId,
+              spanId: spanContext.spanId,
+              traceFlags: spanContext.traceFlags
+            };
+            inputRes.result.forwardedProps = {
+              ...inputRes.result.forwardedProps,
+              __agui_server_context: serverContextData
+            };
+          }
+        }
+      } catch (e) {
+        (_l = logger.debug) == null ? void 0 : _l.call(logger, "Failed to create server span:", e);
+      }
+    }
     let cleanupCalled = false;
     const safeCleanup = () => {
       var _a3, _b2, _c2;
@@ -491,9 +591,50 @@ function createServerAdapter2(createAgent, options) {
         }
       }
     };
+    const eventsResult = safe(
+      () => handler2(
+        inputRes.result,
+        createAgentRes.result.agent
+      )
+    );
+    if ("error" in eventsResult) {
+      const { error } = eventsResult;
+      (_m = logger.error) == null ? void 0 : _m.call(logger, { err: error }, "Run agent failed");
+      if (serverSpan) {
+        try {
+          serverSpan.otelSpan.setStatus({
+            code: 2,
+            // SpanStatusCode.ERROR
+            message: error instanceof Error ? error.message : String(error)
+          });
+          serverSpan.otelSpan.setAttribute("error.type", error instanceof Error ? error.name : "UnknownError");
+          serverSpan.otelSpan.setAttribute("error.message", error instanceof Error ? error.message : String(error));
+          serverSpan.end();
+        } catch (e) {
+          (_n = logger.debug) == null ? void 0 : _n.call(logger, "Failed to update server span with error status:", e);
+        }
+      }
+      const errorCode = (0, import_agent_shared3.isErrorWithCode)(error) ? error.code : ErrorCode.INTERNAL_ERROR;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return new Response(
+        JSON.stringify({
+          error: {
+            code: errorCode,
+            message: errorMessage
+          },
+          requestId
+        }),
+        {
+          status: 500,
+          headers: { "Content-Type": "application/json" }
+        }
+      );
+    }
+    const { result: events } = eventsResult;
+    let heartbeat;
     const stream = new ReadableStream({
       async start(controller) {
-        var _a3, _b2, _c2, _d2;
+        var _a3, _b2, _c2, _d2, _e2;
         const encoder = new TextEncoder();
         heartbeat = setInterval(() => {
           controller.enqueue(encoder.encode(":ping\n\n"));
@@ -532,13 +673,21 @@ function createServerAdapter2(createAgent, options) {
           if (heartbeat) clearInterval(heartbeat);
           controller.close();
           safeCleanup();
+          if (serverSpan) {
+            serverSpan.end();
+            (_e2 = logger.debug) == null ? void 0 : _e2.call(logger, "\u2713 Server span ended");
+          }
         }
       },
       cancel() {
-        var _a3;
+        var _a3, _b2;
         (_a3 = logger.info) == null ? void 0 : _a3.call(logger, "Request cancelled by client");
         if (heartbeat) clearInterval(heartbeat);
         safeCleanup();
+        if (serverSpan) {
+          serverSpan.end();
+          (_b2 = logger.debug) == null ? void 0 : _b2.call(logger, "\u2713 Server span ended (cancelled)");
+        }
       }
     });
     const headers = new Headers({
@@ -558,6 +707,15 @@ async function safeAsync(fn) {
     return { error };
   }
 }
+function safe(fn) {
+  try {
+    return {
+      result: fn()
+    };
+  } catch (error) {
+    return { error };
+  }
+}
 
 // src/agui/healthz/index.ts
 var healthz_exports = {};
@@ -756,6 +914,25 @@ var import_cors = __toESM(require("cors"));
 var import_async_hooks = require("async_hooks");
 var import_server8 = require("@whatwg-node/server");
 var DefaultFetchAPI = __toESM(require("@whatwg-node/fetch"));
+var observabilitySetupPromise = null;
+var observabilitySetupComplete = false;
+async function setupObservabilityIfAvailable(configs) {
+  if (observabilitySetupComplete) {
+    return;
+  }
+  if (observabilitySetupPromise) {
+    return observabilitySetupPromise;
+  }
+  observabilitySetupPromise = (async () => {
+    try {
+      const { setupObservability: setupObservability2 } = await import("@cloudbase/agent-observability/server");
+      await setupObservability2(configs);
+      observabilitySetupComplete = true;
+    } catch (error) {
+    }
+  })();
+  return observabilitySetupPromise;
+}
 var preparedAgentStorage = new import_async_hooks.AsyncLocalStorage();
 function agentCloneFn() {
   const preparedAgent = preparedAgentStorage.getStore();
@@ -790,33 +967,77 @@ function createExpressRoutes({
   express,
   useAGUI: _useAGUI,
   aguiOptions,
-  logger: _logger
+  logger: _logger,
+  observability
 }) {
-  var _a, _b, _c;
+  var _a, _b, _c, _d;
   const useAGUI = _useAGUI ?? true;
   const logger = _logger ?? import_agent_shared2.noopLogger;
-  const basePath = _basePath ?? (process.env.TENCENTCLOUD_RUNENV === "SCF" ? "/v1/aibot/bots/:agentId/" : "/");
+  const userProvidedBasePath = _basePath !== void 0;
   const serverLogger = ((_a = logger.child) == null ? void 0 : _a.call(logger, { component: "server" })) ?? logger;
-  (_b = serverLogger.debug) == null ? void 0 : _b.call(serverLogger, { basePath, useAGUI }, "Initializing server routes");
-  const sendMessageServerAdapter = useAGUI ? sendMessageAGUI_exports.createServerAdapter(createAgent, { logger: serverLogger }) : sendMessage_exports.createServerAdapter(createAgent);
-  if (useAGUI) {
-    createAGUIRoute({
-      basePath,
-      express,
-      createAgent,
-      logger: serverLogger,
-      ...aguiOptions || {}
+  (_b = serverLogger.debug) == null ? void 0 : _b.call(
+    serverLogger,
+    { basePath: _basePath, useAGUI, userProvidedBasePath },
+    "Initializing server routes"
+  );
+  if (observability) {
+    setupObservabilityIfAvailable(observability).catch(() => {
     });
   }
+  const sendMessageServerAdapter = useAGUI ? sendMessageAGUI_exports.createServerAdapter(createAgent, {
+    logger: serverLogger
+  }) : sendMessage_exports.createServerAdapter(createAgent);
   const openaiServerAdapter = openai_exports.createServerAdapter(createAgent);
   const healthzServerAdapter = healthz_exports.serverAdapter;
-  express.use(`${basePath}send-message`, sendMessageServerAdapter);
-  express.use(`${basePath}healthz`, healthzServerAdapter);
-  express.use(`${basePath}chat/completions`, openaiServerAdapter);
-  (_c = serverLogger.info) == null ? void 0 : _c.call(serverLogger, { basePath }, "Server routes initialized");
+  if (userProvidedBasePath) {
+    const basePath = _basePath;
+    if (useAGUI) {
+      createAGUIRoute({
+        basePath,
+        express,
+        createAgent,
+        logger: serverLogger,
+        ...aguiOptions || {}
+      });
+    }
+    express.use(`${basePath}send-message`, sendMessageServerAdapter);
+    express.use(`${basePath}healthz`, healthzServerAdapter);
+    express.use(`${basePath}chat/completions`, openaiServerAdapter);
+    (_c = serverLogger.info) == null ? void 0 : _c.call(serverLogger, { basePath }, "Server routes initialized");
+  } else {
+    const simplePath = "/";
+    const scfPath = "/v1/aibot/bots/:agentId/";
+    if (useAGUI) {
+      createAGUIRoute({
+        basePath: simplePath,
+        express,
+        createAgent,
+        logger: serverLogger,
+        ...aguiOptions || {}
+      });
+      createAGUIRoute({
+        basePath: scfPath,
+        express,
+        createAgent,
+        logger: serverLogger,
+        ...aguiOptions || {}
+      });
+    }
+    express.use(`${simplePath}send-message`, sendMessageServerAdapter);
+    express.use(`${simplePath}healthz`, healthzServerAdapter);
+    express.use(`${simplePath}chat/completions`, openaiServerAdapter);
+    express.use(`${scfPath}send-message`, sendMessageServerAdapter);
+    express.use(`${scfPath}healthz`, healthzServerAdapter);
+    express.use(`${scfPath}chat/completions`, openaiServerAdapter);
+    (_d = serverLogger.info) == null ? void 0 : _d.call(
+      serverLogger,
+      { simplePath, scfPath },
+      "Server routes initialized (dual endpoints)"
+    );
+  }
   return express;
 }
-var AGUIRpcHandlerPromise = null;
+var AGUIRpcHandlerPromiseMap = /* @__PURE__ */ new Map();
 function getAGUIRpcHandler({
   createAgent,
   runtimeOptions,
@@ -826,8 +1047,9 @@ function getAGUIRpcHandler({
   logger,
   requestId
 }) {
-  if (AGUIRpcHandlerPromise) return AGUIRpcHandlerPromise;
-  AGUIRpcHandlerPromise = (async () => {
+  const cached = AGUIRpcHandlerPromiseMap.get(basePath);
+  if (cached) return cached;
+  const handlerPromise = (async () => {
     const { agent } = await createAgent({ request, logger, requestId });
     const templateAgent = "toAGUIAgent" in agent ? agent.toAGUIAgent() : agent;
     templateAgent.clone = agentCloneFn;
@@ -844,7 +1066,8 @@ function getAGUIRpcHandler({
       ...endpointOptions || {}
     });
   })();
-  return AGUIRpcHandlerPromise;
+  AGUIRpcHandlerPromiseMap.set(basePath, handlerPromise);
+  return handlerPromise;
 }
 function createAGUIRoute({
   express,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbase/agent-server",
-  "version": "0.0.15",
+  "version": "0.0.18",
   "main": "dist/index.js",
   "files": [
     "dist/",
@@ -20,10 +20,16 @@
     "express": "^5.1.0",
     "openai": "6.3.0",
     "uuid": "^10.0.0",
-    "@cloudbase/agent-shared": "^0.0.15"
+    "@cloudbase/agent-shared": "^0.0.18"
   },
   "peerDependencies": {
-    "zod": "^3.25.0 || ^4.0.0"
+    "zod": "^3.25.0 || ^4.0.0",
+    "@cloudbase/agent-observability": "0.0.18"
+  },
+  "peerDependenciesMeta": {
+    "@cloudbase/agent-observability": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/cors": "^2.8.19",