@cloudbase/agent-server 0.0.15 → 0.0.16

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,45 @@ var ErrorCode = {
 };
 
 // src/agui/sendMessageAGUI/server.ts
+var startObservation;
+var setupObservability;
+var observabilityLoadAttempted = false;
+async function loadObservability() {
+  if (!observabilityLoadAttempted) {
+    observabilityLoadAttempted = true;
+    try {
+      const obs = await import("@cloudbase/agent-observability");
+      const obsServer = await import("@cloudbase/agent-observability/server");
+      startObservation = obs.startObservation;
+      setupObservability = obsServer.setupObservability;
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+  return !!startObservation;
+}
+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;
     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 +507,46 @@ 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) {
+          serverSpan = startObservation(
+            "AG-UI.Server",
+            {
+              "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
+            },
+            { asType: "span" }
+          );
+          const spanContext = serverSpan.otelSpan.spanContext();
+          serverContextData = {
+            traceId: spanContext.traceId,
+            spanId: spanContext.spanId,
+            traceFlags: spanContext.traceFlags
+          };
+          inputRes.result.forwardedProps = {
+            ...inputRes.result.forwardedProps,
+            __agui_server_context: serverContextData
+          };
+          (_i = logger.debug) == null ? void 0 : _i.call(logger, "\u2713 Server span created:", {
+            traceId: serverContextData.traceId,
+            spanId: serverContextData.spanId
+          });
+        } else {
+          (_j = logger.debug) == null ? void 0 : _j.call(logger, "Observability not ready, skipping span creation");
+        }
+      } catch (e) {
+        (_k = logger.debug) == null ? void 0 : _k.call(logger, "Failed to create server span:", e);
+      }
+    }
     let cleanupCalled = false;
     const safeCleanup = () => {
       var _a3, _b2, _c2;
@@ -491,9 +559,36 @@ function createServerAdapter2(createAgent, options) {
         }
       }
     };
+    const eventsResult = safe(
+      () => handler2(
+        inputRes.result,
+        createAgentRes.result.agent
+      )
+    );
+    if ("error" in eventsResult) {
+      const { error } = eventsResult;
+      (_l = logger.error) == null ? void 0 : _l.call(logger, { err: error }, "Run agent failed");
+      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 +627,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 +661,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 +868,13 @@ 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"));
+async function setupObservabilityIfAvailable(configs) {
+  try {
+    const { setupObservability: setupObservability2 } = await import("@cloudbase/agent-observability/server");
+    await setupObservability2(configs);
+  } catch (error) {
+  }
+}
 var preparedAgentStorage = new import_async_hooks.AsyncLocalStorage();
 function agentCloneFn() {
   const preparedAgent = preparedAgentStorage.getStore();
@@ -790,33 +909,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 +989,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 +1008,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.16",
   "main": "dist/index.js",
   "files": [
     "dist/",
@@ -20,11 +20,14 @@
     "express": "^5.1.0",
     "openai": "6.3.0",
     "uuid": "^10.0.0",
-    "@cloudbase/agent-shared": "^0.0.15"
+    "@cloudbase/agent-shared": "^0.0.16"
   },
   "peerDependencies": {
     "zod": "^3.25.0 || ^4.0.0"
   },
+  "optionalDependencies": {
+    "@cloudbase/agent-observability": "0.0.16"
+  },
   "devDependencies": {
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.3",