@cuylabs/agent-foundry-agentserver-invocations 4.1.0 → 4.2.0

package/README.md

@@ -59,6 +59,26 @@ await runInvocationsServer({
 | `GET` | `/readiness` | Foundry readiness probe |
 | `GET` | `/readyz` | Readiness alias |
 
+`/readiness` and `/readyz` return the Python-compatible readiness body:
+
+```json
+{ "status": "healthy" }
+```
+
+## Operations
+
+The host mirrors the Python request-span lifecycle for the Invocations
+protocol. It creates OpenTelemetry server spans named `invoke_agent`,
+`get_invocation`, and `cancel_invocation`, propagates invocation/session IDs as
+baggage, records handler errors on the active span, and ends streaming spans
+only after the HTTP response finishes or the client disconnects.
+
+By default, `runInvocationsServer()` also logs startup configuration and drains
+in-flight requests for 30 seconds during `close()` before forcing sockets
+closed. Pass `gracefulShutdownTimeoutSeconds` to tune that behavior, or
+`configureObservability: false` if the containing application owns exporter
+initialization itself.
+
 ## Python Mapping
 
 This package maps to:

package/dist/index.d.ts

@@ -268,6 +268,17 @@ interface InvocationsServerOptions {
     trustProxy?: boolean | number | string;
     /** Optional logger. Falls back to `console`. */
     logger?: InvocationsServerLogger;
+    /**
+     * Seconds to wait for `close()` to drain in-flight requests before forcing
+     * sockets closed. Defaults to `30`, matching the Python host.
+     */
+    gracefulShutdownTimeoutSeconds?: number;
+    /**
+     * Initialize Azure Monitor / OTLP exporter plumbing from
+     * `APPLICATIONINSIGHTS_CONNECTION_STRING` and `OTEL_EXPORTER_OTLP_ENDPOINT`.
+     * Defaults to `true`; span creation itself always uses OpenTelemetry API.
+     */
+    configureObservability?: boolean;
 }
 interface InvocationsServerLogger {
     info(message: string, meta?: Record<string, unknown>): void;

package/dist/index.js

@@ -323,11 +323,13 @@ import {
   USER_ISOLATION_HEADER,
   AGENTSERVER_CORE_PACKAGE_VERSION,
   buildPlatformServerHeader,
+  configureAgentServerObservability,
   createErrorBody,
   resolveAgentServerConfig,
   resolveInvocationIdentity as resolveInvocationIdentity2,
   resolveRequestId,
-  sanitizeProtocolId
+  sanitizeProtocolId,
+  startAgentServerRequestSpan
 } from "@cuylabs/agent-foundry-agentserver-core";
 
 // src/package-version.ts
@@ -344,6 +346,10 @@ var DEFAULT_HOST = "0.0.0.0";
 var DEFAULT_BODY_LIMIT = "1mb";
 function createInvocationsApp(options) {
   const logger = options.logger ?? defaultLogger();
+  const config = resolveAgentServerConfig({
+    port: options.port,
+    gracefulShutdownTimeoutSeconds: options.gracefulShutdownTimeoutSeconds
+  });
   const trustProxy = options.trustProxy ?? 1;
   const bodyLimit = options.bodyLimit ?? DEFAULT_BODY_LIMIT;
   const appName = options.appName ?? "foundry-invocations-host";
@@ -358,10 +364,22 @@ function createInvocationsApp(options) {
       version: AGENTSERVER_INVOCATIONS_PACKAGE_VERSION
     }
   ]);
+  const observabilityReady = options.configureObservability === false ? Promise.resolve(void 0) : configureAgentServerObservability({ config, logger });
   const app = express();
   app.disable("x-powered-by");
   app.set("trust proxy", trustProxy);
   app.use(express.raw({ type: "*/*", limit: bodyLimit }));
+  app.use(async (_req, _res, next) => {
+    try {
+      await observabilityReady;
+      next();
+    } catch (error) {
+      logger.warn("Foundry Agent Server observability initialization failed", {
+        error: formatError(error)
+      });
+      next();
+    }
+  });
   app.use((req, res, next) => {
     const requestId = resolveRequestId((name) => req.header(name));
     req.agentServerRequestId = requestId;
@@ -390,9 +408,6 @@ function createInvocationsApp(options) {
   app.get("/healthz", (_req, res) => {
     res.json({ ok: true });
   });
-  const readinessHandler = (_req, res) => {
-    res.json({ ok: true, app: appName });
-  };
   app.get("/readiness", readinessHandler);
   app.get("/readyz", readinessHandler);
   app.get("/invocations/docs/openapi.json", (_req, res) => {
@@ -419,10 +434,20 @@ function createInvocationsApp(options) {
       return;
     }
     const ctx = buildContextFromRequest(req, res);
+    const requestSpan = startInvocationRequestSpan({
+      req,
+      res,
+      config,
+      operation: "invoke_agent",
+      invocationId: ctx.invocationId,
+      sessionId: ctx.sessionId,
+      correlationRequestId: ctx.requestId
+    });
     try {
-      await handler.handle(req, res, ctx);
+      await requestSpan.run(() => handler.handle(req, res, ctx));
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
+      requestSpan.recordError(error, "handler_failed");
       logger.error("Invocation handler threw", {
         error: formatError(error),
         invocationId: ctx.invocationId,
@@ -443,35 +468,57 @@ function createInvocationsApp(options) {
   });
   app.get("/invocations/:invocationId", async (req, res) => {
     const handler = handlerProvider();
+    const invocationId = req.params.invocationId ?? "";
+    const sessionId = typeof req.query.agent_session_id === "string" ? req.query.agent_session_id : void 0;
+    const requestSpan = startInvocationRequestSpan({
+      req,
+      res,
+      config,
+      operation: "get_invocation",
+      invocationId,
+      sessionId,
+      correlationRequestId: req.agentServerRequestId
+    });
+    addProtectedHeaders(res, {
+      [INVOCATION_ID_HEADER]: invocationId
+    });
     if (!handler.getStatus) {
-      res.status(404).json(
-        createErrorBody(
-          "not_implemented",
-          "This handler does not expose long-running invocation status."
-        )
-      );
+      res.status(404).json(createErrorBody("not_found", "get_invocation not implemented"));
       return;
     }
     try {
-      await handler.getStatus(req.params.invocationId ?? "", req, res);
+      await requestSpan.run(() => handler.getStatus?.(invocationId, req, res));
     } catch (error) {
+      requestSpan.recordError(error, "internal_error");
       handleHandlerError(res, error, logger, "getStatus");
     }
   });
   const cancelHandler = async (req, res) => {
     const handler = handlerProvider();
+    const invocationId = req.params.invocationId;
+    const sessionId = typeof req.query.agent_session_id === "string" ? req.query.agent_session_id : void 0;
+    const requestSpan = startInvocationRequestSpan({
+      req,
+      res,
+      config,
+      operation: "cancel_invocation",
+      invocationId,
+      sessionId,
+      correlationRequestId: req.agentServerRequestId
+    });
+    addProtectedHeaders(res, {
+      [INVOCATION_ID_HEADER]: invocationId
+    });
     if (!handler.cancel) {
       res.status(404).json(
-        createErrorBody(
-          "not_implemented",
-          "This handler does not expose long-running invocation cancellation."
-        )
+        createErrorBody("not_found", "cancel_invocation not implemented")
       );
       return;
     }
     try {
-      await handler.cancel(req.params.invocationId, req, res);
+      await requestSpan.run(() => handler.cancel?.(invocationId, req, res));
     } catch (error) {
+      requestSpan.recordError(error, "internal_error");
       handleHandlerError(res, error, logger, "cancel");
     }
   };
@@ -490,12 +537,27 @@ function createInvocationsApp(options) {
 }
 async function runInvocationsServer(options) {
   const app = createInvocationsApp(options);
-  const port = resolveAgentServerConfig({ port: options.port }).port;
+  const config = resolveAgentServerConfig({
+    port: options.port,
+    gracefulShutdownTimeoutSeconds: options.gracefulShutdownTimeoutSeconds
+  });
+  const port = config.port;
   const host = options.host ?? DEFAULT_HOST;
   const logger = options.logger ?? defaultLogger();
   const appName = options.appName ?? "foundry-invocations-host";
+  const platformServer = buildPlatformServerHeader([
+    {
+      name: "azure-ai-agentserver-core",
+      version: AGENTSERVER_CORE_PACKAGE_VERSION
+    },
+    {
+      name: "azure-ai-agentserver-invocations",
+      version: AGENTSERVER_INVOCATIONS_PACKAGE_VERSION
+    }
+  ]);
   const server = await new Promise((resolve, reject) => {
     const httpServer = app.listen(port, host, () => {
+      logStartupConfiguration(logger, config, platformServer);
       logger.info(
         `${appName} listening on http://${host}:${port}/invocations`
       );
@@ -508,21 +570,107 @@ async function runInvocationsServer(options) {
     port,
     host,
     async close() {
-      await new Promise((resolve, reject) => {
-        server.close((error) => {
-          if (!error || error.code === "ERR_SERVER_NOT_RUNNING") {
-            resolve();
-            return;
-          }
-          reject(error);
-        });
-      });
+      await closeServerWithTimeout(
+        server,
+        config.gracefulShutdownTimeoutSeconds
+      );
       if (options.handler instanceof InvocationHandler) {
         await options.handler.close?.();
       }
     }
   };
 }
+function startInvocationRequestSpan(options) {
+  const span = startAgentServerRequestSpan({
+    config: options.config,
+    headers: (name) => options.req.header(name),
+    requestId: options.invocationId,
+    operation: options.operation,
+    operationName: options.operation,
+    instrumentationScope: "Azure.AI.AgentServer.Invocations",
+    invocationId: options.invocationId,
+    sessionId: options.sessionId,
+    correlationRequestId: options.correlationRequestId
+  });
+  let finished = false;
+  options.res.once("finish", () => {
+    finished = true;
+    span.end();
+  });
+  options.res.once("close", () => {
+    if (finished) {
+      span.end();
+      return;
+    }
+    span.end(new Error("HTTP response closed before finish"));
+  });
+  return span;
+}
+async function closeServerWithTimeout(server, timeoutSeconds) {
+  const closePromise = new Promise((resolve, reject) => {
+    server.close((error) => {
+      if (!error || error.code === "ERR_SERVER_NOT_RUNNING") {
+        resolve();
+        return;
+      }
+      reject(error);
+    });
+  });
+  if (timeoutSeconds <= 0) {
+    await closePromise;
+    return;
+  }
+  let timeout;
+  const timeoutPromise = new Promise((resolve) => {
+    timeout = setTimeout(() => {
+      server.closeAllConnections?.();
+      resolve();
+    }, timeoutSeconds * 1e3);
+  });
+  try {
+    await Promise.race([closePromise, timeoutPromise]);
+  } finally {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+  }
+}
+function logStartupConfiguration(logger, config, platformServer) {
+  logger.info("Foundry Agent Server platform environment", {
+    isHosted: config.isHosted,
+    agentName: config.agentName || "(not set)",
+    agentVersion: config.agentVersion || "(not set)",
+    port: config.port,
+    sessionId: config.sessionId || "(not set)",
+    sseKeepAliveIntervalSeconds: config.sseKeepAliveIntervalSeconds > 0 ? config.sseKeepAliveIntervalSeconds : "disabled"
+  });
+  logger.info("Foundry Agent Server connectivity", {
+    projectEndpoint: maskUri(config.projectEndpoint),
+    otlpEndpoint: maskUri(config.otlpEndpoint),
+    applicationInsightsConfigured: Boolean(
+      config.applicationInsightsConnectionString.trim()
+    )
+  });
+  logger.info("Foundry Agent Server host options", {
+    gracefulShutdownTimeoutSeconds: config.gracefulShutdownTimeoutSeconds,
+    platformServer
+  });
+}
+function readinessHandler(_req, res) {
+  res.json({ status: "healthy" });
+}
+function maskUri(uri) {
+  const normalized = uri.trim();
+  if (!normalized) {
+    return "(not set)";
+  }
+  try {
+    const parsed = new URL(normalized);
+    return `${parsed.protocol}//${parsed.host}`;
+  } catch {
+    return "(redacted)";
+  }
+}
 function makeHandlerProvider(input) {
   if (typeof input === "function") {
     return input;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-foundry-agentserver-invocations",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "TypeScript Foundry Agent Server Invocations-protocol host (mirrors azure-ai-agentserver-invocations)",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,9 +18,10 @@
   ],
   "dependencies": {
     "express": "^5.0.0",
-    "@cuylabs/agent-foundry-agentserver-core": "^4.1.0"
+    "@cuylabs/agent-foundry-agentserver-core": "^4.2.0"
   },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
     "@types/express": "^5.0.0",
     "@types/node": "^22.0.0",
     "tsup": "^8.0.0",