@cuylabs/agent-foundry-agentserver-core 4.8.1 → 4.9.0

package/README.md

@@ -4,8 +4,10 @@ Shared host utilities for TypeScript Foundry Agent Server protocol packages.
 
 This package mirrors the protocol-agnostic parts of Python
 `azure-ai-agentserver-core`: configuration resolution, request/session ID
-sanitization, request correlation IDs, server-version header formatting, and
-standard error envelopes. Protocol packages such as
+sanitization, request correlation IDs, server-version header formatting,
+standard error envelopes, common Express host middleware, readiness/liveness
+handlers, request logging, graceful shutdown helpers, and startup configuration
+logging. Protocol packages such as
 `@cuylabs/agent-foundry-agentserver-invocations` build their HTTP surface on top
 of these helpers.
 
@@ -18,6 +20,10 @@ sets the Foundry baggage keys used by the Python host:
 ```text
 azure.ai.agentserver.invocation_id
 azure.ai.agentserver.session_id
+azure.ai.agentserver.response_id
+azure.ai.agentserver.conversation_id
+azure.ai.agentserver.streaming
+azure.ai.agentserver.x-request-id
 ```
 
 Exporter setup is optional and is driven by the same environment variables used
@@ -31,3 +37,17 @@ by hosted agents:
 Protocol packages call `configureAgentServerObservability()` by default. Apps
 that already own OpenTelemetry setup can disable package-managed exporter setup
 at the protocol layer and keep the span/baggage helpers.
+
+## Python Comparison
+
+Compare this package to Python `azure-ai-agentserver-core`, not to a protocol
+package. Python exposes an `AgentServerHost` built on ASGI, Starlette, and
+Hypercorn. This TypeScript package exposes the equivalent protocol-agnostic
+host pieces for Express and Node HTTP, then protocol packages compose those
+pieces into their own server entry points.
+
+`@cuylabs/agent-foundry-agentserver-responses` depends on this package in the
+same way Python `azure-ai-agentserver-responses` depends on
+`azure-ai-agentserver-core`. The local `@cuylabs/agent-foundry-hosting`
+package is different: it is agents-ts runtime glue, not a direct Python SDK
+peer.

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { Server } from 'node:http';
+import { Request, Response, NextFunction, Express } from 'express';
 import { Span, Context } from '@opentelemetry/api';
 
 interface AgentServerConfig {
@@ -36,11 +38,14 @@ interface AgentServerErrorBody {
         message: string;
         type?: string;
         details?: Array<Record<string, unknown>>;
+        additionalInfo?: Record<string, unknown>;
     };
 }
 declare function createErrorBody(code: string, message: string, options?: {
     type?: string;
     details?: Array<Record<string, unknown>>;
+    additionalInfo?: Record<string, unknown>;
+    requestId?: string;
 }): AgentServerErrorBody;
 
 declare const REQUEST_ID_HEADER: "x-request-id";
@@ -48,6 +53,7 @@ declare const INVOCATION_ID_HEADER: "x-agent-invocation-id";
 declare const SESSION_ID_HEADER: "x-agent-session-id";
 declare const USER_ISOLATION_HEADER: "x-agent-user-isolation-key";
 declare const CHAT_ISOLATION_HEADER: "x-agent-chat-isolation-key";
+declare const CLIENT_HEADER_PREFIX: "x-client-";
 declare const SESSION_ID_HEADERS: readonly ["x-agent-session-id", "x-foundry-agent-session-id", "x-ms-agent-session-id"];
 declare const INVOCATION_ID_HEADERS: readonly ["x-agent-invocation-id", "x-foundry-invocation-id", "x-ms-invocation-id", "x-invocation-id"];
 type HeaderGetter = (name: string) => string | undefined;
@@ -66,10 +72,47 @@ interface InvocationIdentity {
     sessionId: string;
     invocationId: string;
 }
+interface AgentIsolationContext {
+    userKey?: string;
+    chatKey?: string;
+}
 declare function resolveInvocationIdentity(input: InvocationIdentityInput): InvocationIdentity;
 declare function resolveRequestId(header: HeaderGetter): string;
+declare function resolveAgentIsolation(header: HeaderGetter): AgentIsolationContext;
+declare function collectClientHeaders(headers: Record<string, string | string[] | undefined>): Record<string, string>;
 declare function sanitizeProtocolId(value: string | undefined, fallback: string): string;
 
+interface AgentServerLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    debug?(message: string, meta?: Record<string, unknown>): void;
+}
+interface AgentServerExpressRequest extends Request {
+    agentServerRequestId?: string;
+}
+interface AgentServerRequestHeadersMiddlewareOptions {
+    platformServer: string;
+}
+declare function agentServerRequestHeadersMiddleware(options: AgentServerRequestHeadersMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => void;
+declare function addProtectedHeaders(res: Response, headers: Record<string, string>, options?: {
+    sanitizeHeaderNames?: readonly string[];
+}): void;
+declare function agentServerLoggingMiddleware(logger: AgentServerLogger): (req: Request, res: Response, next: NextFunction) => void;
+declare function readinessHandler(_req: Request, res: Response): void;
+declare function healthzHandler(_req: Request, res: Response): void;
+declare function methodNotAllowed(allowedMethods: readonly string[]): (_req: Request, res: Response) => void;
+declare function notFoundMiddleware(): (_req: Request, res: Response, _next: NextFunction) => void;
+declare function errorMiddleware(logger: AgentServerLogger): (err: unknown, req: Request, res: Response, next: NextFunction) => void;
+declare function closeServerWithTimeout(server: Server, timeoutSeconds: number): Promise<void>;
+declare function configureExpressAgentServerApp(app: Express, options?: {
+    trustProxy?: boolean | number | string;
+}): void;
+declare function logAgentServerStartupConfiguration(logger: AgentServerLogger, config: AgentServerConfig, platformServer: string): void;
+declare function maskUri(uri: string): string;
+declare function formatError(error: unknown): string;
+declare function defaultAgentServerLogger(scope: string): AgentServerLogger;
+
 interface AgentServerObservabilityLogger {
     info(message: string, meta?: Record<string, unknown>): void;
     warn(message: string, meta?: Record<string, unknown>): void;
@@ -98,6 +141,9 @@ declare const AGENTSERVER_CORE_PACKAGE_VERSION: string;
 declare const AGENTSERVER_INVOCATION_ID_BAGGAGE = "azure.ai.agentserver.invocation_id";
 declare const AGENTSERVER_SESSION_ID_BAGGAGE = "azure.ai.agentserver.session_id";
 declare const AGENTSERVER_CONVERSATION_ID_BAGGAGE = "azure.ai.agentserver.conversation_id";
+declare const AGENTSERVER_RESPONSE_ID_BAGGAGE = "azure.ai.agentserver.response_id";
+declare const AGENTSERVER_STREAMING_BAGGAGE = "azure.ai.agentserver.streaming";
+declare const AGENTSERVER_REQUEST_ID_BAGGAGE = "azure.ai.agentserver.x-request-id";
 declare const ATTR_SERVICE_NAME = "service.name";
 declare const ATTR_GEN_AI_SYSTEM = "gen_ai.system";
 declare const ATTR_GEN_AI_PROVIDER_NAME = "gen_ai.provider.name";
@@ -112,6 +158,9 @@ declare const ATTR_SESSION_ID = "microsoft.session.id";
 declare const ATTR_INVOCATION_ID = "azure.ai.agentserver.invocations.id";
 declare const ATTR_INVOCATIONS_ERROR_CODE = "azure.ai.agentserver.invocations.error.code";
 declare const ATTR_INVOCATIONS_ERROR_MESSAGE = "azure.ai.agentserver.invocations.error.message";
+declare const ATTR_RESPONSES_STREAMING = "azure.ai.agentserver.responses.streaming";
+declare const ATTR_RESPONSES_ERROR_CODE = "azure.ai.agentserver.responses.error.code";
+declare const ATTR_RESPONSES_ERROR_MESSAGE = "azure.ai.agentserver.responses.error.message";
 interface AgentServerRequestSpanOptions {
     config: Pick<AgentServerConfig, "agentId" | "agentName" | "agentVersion" | "projectArmId">;
     headers: HeaderGetter;
@@ -121,6 +170,9 @@ interface AgentServerRequestSpanOptions {
     instrumentationScope?: string;
     invocationId?: string;
     sessionId?: string;
+    responseId?: string;
+    conversationId?: string;
+    streaming?: boolean | string;
     correlationRequestId?: string;
 }
 interface AgentServerRequestSpan {
@@ -140,10 +192,13 @@ declare function startAgentServerRequestSpan(options: AgentServerRequestSpanOpti
 declare function withAgentServerBaggage(sourceContext: Context, values: {
     invocationId?: string;
     sessionId?: string;
+    responseId?: string;
+    conversationId?: string;
+    streaming?: boolean | string;
     requestId?: string;
 }): Context;
 declare function recordAgentServerSpanError(span: Span, error: unknown, code?: string): void;
 declare function createFoundryEnrichmentSpanProcessor(config: Pick<AgentServerConfig, "agentId" | "agentName" | "agentVersion" | "projectArmId">): AgentServerSpanProcessor;
 declare function flushSpans(timeoutMillis?: number): void;
 
-export { AGENTSERVER_CONVERSATION_ID_BAGGAGE, AGENTSERVER_CORE_PACKAGE_VERSION, AGENTSERVER_INVOCATION_ID_BAGGAGE, AGENTSERVER_SESSION_ID_BAGGAGE, ATTR_FOUNDRY_PROJECT_ID, ATTR_GEN_AI_AGENT_ID, ATTR_GEN_AI_AGENT_NAME, ATTR_GEN_AI_AGENT_VERSION, ATTR_GEN_AI_CONVERSATION_ID, ATTR_GEN_AI_OPERATION_NAME, ATTR_GEN_AI_PROVIDER_NAME, ATTR_GEN_AI_RESPONSE_ID, ATTR_GEN_AI_SYSTEM, ATTR_INVOCATIONS_ERROR_CODE, ATTR_INVOCATIONS_ERROR_MESSAGE, ATTR_INVOCATION_ID, ATTR_SERVICE_NAME, ATTR_SESSION_ID, type AgentServerConfig, type AgentServerConfigOptions, type AgentServerErrorBody, type AgentServerLogLevel, type AgentServerObservabilityHandle, type AgentServerObservabilityLogger, type AgentServerRequestSpan, type AgentServerRequestSpanOptions, type AgentServerSpanProcessor, CHAT_ISOLATION_HEADER, type ConfigureAgentServerObservabilityOptions, type HeaderGetter, INVOCATION_ID_HEADER, INVOCATION_ID_HEADERS, type InvocationIdentity, type InvocationIdentityInput, type QueryGetter, REQUEST_ID_HEADER, SESSION_ID_HEADER, SESSION_ID_HEADERS, USER_ISOLATION_HEADER, buildPlatformServerHeader, buildServerVersionSegment, configureAgentServerObservability, createErrorBody, createFoundryEnrichmentSpanProcessor, flushSpans, recordAgentServerSpanError, resolveAgentServerConfig, resolveGracefulShutdownTimeout, resolveInvocationIdentity, resolveLogLevel, resolvePort, resolveRequestId, resolveSseKeepAliveInterval, sanitizeProtocolId, startAgentServerRequestSpan, withAgentServerBaggage };
+export { AGENTSERVER_CONVERSATION_ID_BAGGAGE, AGENTSERVER_CORE_PACKAGE_VERSION, AGENTSERVER_INVOCATION_ID_BAGGAGE, AGENTSERVER_REQUEST_ID_BAGGAGE, AGENTSERVER_RESPONSE_ID_BAGGAGE, AGENTSERVER_SESSION_ID_BAGGAGE, AGENTSERVER_STREAMING_BAGGAGE, ATTR_FOUNDRY_PROJECT_ID, ATTR_GEN_AI_AGENT_ID, ATTR_GEN_AI_AGENT_NAME, ATTR_GEN_AI_AGENT_VERSION, ATTR_GEN_AI_CONVERSATION_ID, ATTR_GEN_AI_OPERATION_NAME, ATTR_GEN_AI_PROVIDER_NAME, ATTR_GEN_AI_RESPONSE_ID, ATTR_GEN_AI_SYSTEM, ATTR_INVOCATIONS_ERROR_CODE, ATTR_INVOCATIONS_ERROR_MESSAGE, ATTR_INVOCATION_ID, ATTR_RESPONSES_ERROR_CODE, ATTR_RESPONSES_ERROR_MESSAGE, ATTR_RESPONSES_STREAMING, ATTR_SERVICE_NAME, ATTR_SESSION_ID, type AgentIsolationContext, type AgentServerConfig, type AgentServerConfigOptions, type AgentServerErrorBody, type AgentServerExpressRequest, type AgentServerLogLevel, type AgentServerLogger, type AgentServerObservabilityHandle, type AgentServerObservabilityLogger, type AgentServerRequestSpan, type AgentServerRequestSpanOptions, type AgentServerSpanProcessor, CHAT_ISOLATION_HEADER, CLIENT_HEADER_PREFIX, type ConfigureAgentServerObservabilityOptions, type HeaderGetter, INVOCATION_ID_HEADER, INVOCATION_ID_HEADERS, type InvocationIdentity, type InvocationIdentityInput, type QueryGetter, REQUEST_ID_HEADER, SESSION_ID_HEADER, SESSION_ID_HEADERS, USER_ISOLATION_HEADER, addProtectedHeaders, agentServerLoggingMiddleware, agentServerRequestHeadersMiddleware, buildPlatformServerHeader, buildServerVersionSegment, closeServerWithTimeout, collectClientHeaders, configureAgentServerObservability, configureExpressAgentServerApp, createErrorBody, createFoundryEnrichmentSpanProcessor, defaultAgentServerLogger, errorMiddleware, flushSpans, formatError, healthzHandler, logAgentServerStartupConfiguration, maskUri, methodNotAllowed, notFoundMiddleware, readinessHandler, recordAgentServerSpanError, resolveAgentIsolation, resolveAgentServerConfig, resolveGracefulShutdownTimeout, resolveInvocationIdentity, resolveLogLevel, resolvePort, resolveRequestId, resolveSseKeepAliveInterval, sanitizeProtocolId, startAgentServerRequestSpan, withAgentServerBaggage };

package/dist/index.js

@@ -105,12 +105,17 @@ function validateInteger(value, source) {
 
 // src/errors.ts
 function createErrorBody(code, message, options = {}) {
+  const additionalInfo = {
+    ...options.additionalInfo ?? {},
+    ...options.requestId ? { request_id: options.requestId } : {}
+  };
   return {
     error: {
       code,
       message,
       ...options.type ? { type: options.type } : {},
-      ...options.details ? { details: options.details } : {}
+      ...options.details ? { details: options.details } : {},
+      ...Object.keys(additionalInfo).length > 0 ? { additionalInfo } : {}
     }
   };
 }
@@ -122,6 +127,7 @@ var INVOCATION_ID_HEADER = "x-agent-invocation-id";
 var SESSION_ID_HEADER = "x-agent-session-id";
 var USER_ISOLATION_HEADER = "x-agent-user-isolation-key";
 var CHAT_ISOLATION_HEADER = "x-agent-chat-isolation-key";
+var CLIENT_HEADER_PREFIX = "x-client-";
 var SESSION_ID_HEADERS = [
   SESSION_ID_HEADER,
   "x-foundry-agent-session-id",
@@ -155,6 +161,28 @@ function resolveRequestId(header) {
   const incoming = header(REQUEST_ID_HEADER)?.trim();
   return incoming || randomUUID().replaceAll("-", "");
 }
+function resolveAgentIsolation(header) {
+  const userKey = header(USER_ISOLATION_HEADER);
+  const chatKey = header(CHAT_ISOLATION_HEADER);
+  return {
+    ...userKey !== void 0 ? { userKey } : {},
+    ...chatKey !== void 0 ? { chatKey } : {}
+  };
+}
+function collectClientHeaders(headers) {
+  const clientHeaders = {};
+  for (const [name, value] of Object.entries(headers)) {
+    const lowerName = name.toLowerCase();
+    if (!lowerName.startsWith(CLIENT_HEADER_PREFIX)) {
+      continue;
+    }
+    const headerValue = Array.isArray(value) ? value.join(",") : value;
+    if (headerValue !== void 0) {
+      clientHeaders[lowerName] = headerValue;
+    }
+  }
+  return clientHeaders;
+}
 function sanitizeProtocolId(value, fallback) {
   const normalized = value?.trim();
   if (!normalized || normalized.length > MAX_ID_LENGTH || !VALID_ID_RE.test(normalized)) {
@@ -192,6 +220,190 @@ function traceIdFromTraceparent(traceparent) {
   return void 0;
 }
 
+// src/host.ts
+function agentServerRequestHeadersMiddleware(options) {
+  return (req, res, next) => {
+    const requestId = resolveRequestId((name) => req.header(name));
+    req.agentServerRequestId = requestId;
+    addProtectedHeaders(res, {
+      [REQUEST_ID_HEADER]: requestId,
+      "x-platform-server": options.platformServer
+    });
+    next();
+  };
+}
+function addProtectedHeaders(res, headers, options = {}) {
+  const protectedRes = res;
+  if (!protectedRes.__agentServerProtectedHeaders) {
+    const protectedHeaders = /* @__PURE__ */ new Map();
+    const originalSetHeader2 = res.setHeader.bind(res);
+    protectedRes.__agentServerProtectedHeaders = protectedHeaders;
+    protectedRes.__agentServerOriginalSetHeader = originalSetHeader2;
+    res.setHeader = ((name, value) => {
+      const protectedValue = protectedHeaders.get(name.toLowerCase());
+      if (protectedValue !== void 0) {
+        return originalSetHeader2(name, protectedValue);
+      }
+      return originalSetHeader2(name, value);
+    });
+  }
+  const originalSetHeader = protectedRes.__agentServerOriginalSetHeader ?? res.setHeader.bind(res);
+  const sanitizeHeaderNames = new Set(
+    (options.sanitizeHeaderNames ?? [INVOCATION_ID_HEADER, SESSION_ID_HEADER]).map((name) => name.toLowerCase())
+  );
+  for (const [name, value] of Object.entries(headers)) {
+    const lowerName = name.toLowerCase();
+    const safeValue = sanitizeHeaderNames.has(lowerName) ? sanitizeProtocolId(value, value) : value;
+    protectedRes.__agentServerProtectedHeaders.set(lowerName, safeValue);
+    originalSetHeader(name, safeValue);
+  }
+}
+function agentServerLoggingMiddleware(logger) {
+  return (req, res, next) => {
+    const start = Date.now();
+    res.on("finish", () => {
+      logger.info("http request", {
+        method: req.method,
+        path: req.path,
+        statusCode: res.statusCode,
+        durationMs: Date.now() - start,
+        requestId: req.agentServerRequestId,
+        clientRequestId: req.header("x-ms-client-request-id")
+      });
+    });
+    next();
+  };
+}
+function readinessHandler(_req, res) {
+  res.json({ status: "healthy" });
+}
+function healthzHandler(_req, res) {
+  res.json({ ok: true });
+}
+function methodNotAllowed(allowedMethods) {
+  return (_req, res) => {
+    res.setHeader("Allow", allowedMethods.join(", "));
+    res.status(405).json(
+      createErrorBody(
+        "method_not_allowed",
+        `Allowed methods: ${allowedMethods.join(", ")}`
+      )
+    );
+  };
+}
+function notFoundMiddleware() {
+  return (_req, res, _next) => {
+    res.status(404).json(createErrorBody("not_found", "No route matched this path."));
+  };
+}
+function errorMiddleware(logger) {
+  return (err, req, res, _next) => {
+    logger.error("Unhandled middleware error", { error: formatError(err) });
+    if (res.headersSent) {
+      res.end();
+      return;
+    }
+    res.status(500).json(
+      createErrorBody(
+        "internal_error",
+        err instanceof Error ? err.message : String(err),
+        {
+          requestId: req.agentServerRequestId
+        }
+      )
+    );
+  };
+}
+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 configureExpressAgentServerApp(app, options = {}) {
+  app.disable("x-powered-by");
+  app.set("trust proxy", options.trustProxy ?? 1);
+}
+function logAgentServerStartupConfiguration(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 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 formatError(error) {
+  if (error instanceof Error) {
+    return error.stack ?? error.message;
+  }
+  return String(error);
+}
+function defaultAgentServerLogger(scope) {
+  return {
+    info: (message, meta) => {
+      if (meta) {
+        console.log(`[${scope}] ${message}`, meta);
+      } else {
+        console.log(`[${scope}] ${message}`);
+      }
+    },
+    warn: (message, meta) => {
+      console.warn(`[${scope}] ${message}`, meta ?? "");
+    },
+    error: (message, meta) => {
+      console.error(`[${scope}] ${message}`, meta ?? "");
+    }
+  };
+}
+
 // src/tracing.ts
 import {
   SpanKind,
@@ -204,6 +416,9 @@ import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-ho
 var AGENTSERVER_INVOCATION_ID_BAGGAGE = "azure.ai.agentserver.invocation_id";
 var AGENTSERVER_SESSION_ID_BAGGAGE = "azure.ai.agentserver.session_id";
 var AGENTSERVER_CONVERSATION_ID_BAGGAGE = "azure.ai.agentserver.conversation_id";
+var AGENTSERVER_RESPONSE_ID_BAGGAGE = "azure.ai.agentserver.response_id";
+var AGENTSERVER_STREAMING_BAGGAGE = "azure.ai.agentserver.streaming";
+var AGENTSERVER_REQUEST_ID_BAGGAGE = "azure.ai.agentserver.x-request-id";
 var ATTR_SERVICE_NAME = "service.name";
 var ATTR_GEN_AI_SYSTEM = "gen_ai.system";
 var ATTR_GEN_AI_PROVIDER_NAME = "gen_ai.provider.name";
@@ -218,6 +433,9 @@ var ATTR_SESSION_ID = "microsoft.session.id";
 var ATTR_INVOCATION_ID = "azure.ai.agentserver.invocations.id";
 var ATTR_INVOCATIONS_ERROR_CODE = "azure.ai.agentserver.invocations.error.code";
 var ATTR_INVOCATIONS_ERROR_MESSAGE = "azure.ai.agentserver.invocations.error.message";
+var ATTR_RESPONSES_STREAMING = "azure.ai.agentserver.responses.streaming";
+var ATTR_RESPONSES_ERROR_CODE = "azure.ai.agentserver.responses.error.code";
+var ATTR_RESPONSES_ERROR_MESSAGE = "azure.ai.agentserver.responses.error.message";
 var SERVICE_NAME_VALUE = "azure.ai.agentserver";
 var GEN_AI_SYSTEM_VALUE = "azure.ai.agentserver";
 var GEN_AI_PROVIDER_NAME_VALUE = "AzureAI Hosted Agents";
@@ -250,6 +468,11 @@ function startAgentServerRequestSpan(options) {
   setAttribute(attributes, ATTR_FOUNDRY_PROJECT_ID, config.projectArmId);
   setAttribute(attributes, ATTR_SESSION_ID, options.sessionId);
   setAttribute(attributes, ATTR_INVOCATION_ID, options.invocationId);
+  setAttribute(attributes, ATTR_GEN_AI_RESPONSE_ID, options.responseId);
+  setAttribute(attributes, ATTR_GEN_AI_CONVERSATION_ID, options.conversationId);
+  if (options.streaming !== void 0) {
+    attributes[ATTR_RESPONSES_STREAMING] = typeof options.streaming === "boolean" ? options.streaming : options.streaming === "true";
+  }
   const requestId = options.headers("x-request-id") ?? options.correlationRequestId;
   setAttribute(attributes, "x_request_id", requestId);
   const span = trace.getTracer(instrumentationScope).startSpan(
@@ -265,6 +488,9 @@ function startAgentServerRequestSpan(options) {
     {
       invocationId: options.invocationId,
       sessionId: options.sessionId,
+      responseId: options.responseId,
+      conversationId: options.conversationId,
+      streaming: options.streaming,
       requestId
     }
   );
@@ -314,10 +540,28 @@ function withAgentServerBaggage(sourceContext, values) {
     });
   }
   if (values.requestId) {
+    baggage = baggage.setEntry(AGENTSERVER_REQUEST_ID_BAGGAGE, {
+      value: values.requestId
+    });
     baggage = baggage.setEntry("x_request_id", {
       value: values.requestId
     });
   }
+  if (values.responseId !== void 0) {
+    baggage = baggage.setEntry(AGENTSERVER_RESPONSE_ID_BAGGAGE, {
+      value: values.responseId
+    });
+  }
+  if (values.conversationId !== void 0) {
+    baggage = baggage.setEntry(AGENTSERVER_CONVERSATION_ID_BAGGAGE, {
+      value: values.conversationId
+    });
+  }
+  if (values.streaming !== void 0) {
+    baggage = baggage.setEntry(AGENTSERVER_STREAMING_BAGGAGE, {
+      value: typeof values.streaming === "boolean" ? String(values.streaming) : values.streaming
+    });
+  }
   return propagation.setBaggage(sourceContext, baggage);
 }
 function recordAgentServerSpanError(span, error, code = "internal_error") {
@@ -450,7 +694,7 @@ async function configureAgentServerObservabilityOnce(options) {
       return makeHandle(exporters, shutdownCallbacks);
     } catch (error) {
       logger.warn("Failed to initialize Azure Monitor observability", {
-        error: formatError(error)
+        error: formatError2(error)
       });
     }
   }
@@ -469,7 +713,7 @@ async function configureAgentServerObservabilityOnce(options) {
       return makeHandle(exporters, shutdownCallbacks, setup2.configured);
     } catch (error) {
       logger.warn("Failed to initialize OTLP observability", {
-        error: formatError(error)
+        error: formatError2(error)
       });
     }
   }
@@ -498,7 +742,7 @@ async function createOtlpSpanProcessor(config, logger) {
     return new BatchSpanProcessor(new OTLPTraceExporter({ url: endpoint }));
   } catch (error) {
     logger.warn("Failed to initialize OTLP span processor", {
-      error: formatError(error)
+      error: formatError2(error)
     });
     return void 0;
   }
@@ -520,7 +764,7 @@ async function createResource(config, logger) {
     return resources.resourceFromAttributes(attributes);
   } catch (error) {
     logger.debug?.("OpenTelemetry resource package unavailable", {
-      error: formatError(error)
+      error: formatError2(error)
     });
     return void 0;
   }
@@ -546,7 +790,7 @@ async function ensureTraceProvider(config, logger, spanProcessors) {
     }
   } catch (error) {
     logger.debug?.("OpenTelemetry API provider inspection failed", {
-      error: formatError(error)
+      error: formatError2(error)
     });
   }
   try {
@@ -564,19 +808,15 @@ async function ensureTraceProvider(config, logger, spanProcessors) {
     };
   } catch (error) {
     logger.warn("Failed to initialize local OpenTelemetry tracer provider", {
-      error: formatError(error)
+      error: formatError2(error)
     });
     return { configured: false };
   }
 }
 async function importOptional(specifier) {
-  const dynamicImport = new Function(
-    "specifier",
-    "return import(specifier)"
-  );
-  return await dynamicImport(specifier);
+  return await import(specifier);
 }
-function formatError(error) {
+function formatError2(error) {
   if (error instanceof Error) {
     return error.stack ?? error.message;
   }
@@ -627,7 +867,10 @@ export {
   AGENTSERVER_CONVERSATION_ID_BAGGAGE,
   AGENTSERVER_CORE_PACKAGE_VERSION,
   AGENTSERVER_INVOCATION_ID_BAGGAGE,
+  AGENTSERVER_REQUEST_ID_BAGGAGE,
+  AGENTSERVER_RESPONSE_ID_BAGGAGE,
   AGENTSERVER_SESSION_ID_BAGGAGE,
+  AGENTSERVER_STREAMING_BAGGAGE,
   ATTR_FOUNDRY_PROJECT_ID,
   ATTR_GEN_AI_AGENT_ID,
   ATTR_GEN_AI_AGENT_NAME,
@@ -640,22 +883,42 @@ export {
   ATTR_INVOCATIONS_ERROR_CODE,
   ATTR_INVOCATIONS_ERROR_MESSAGE,
   ATTR_INVOCATION_ID,
+  ATTR_RESPONSES_ERROR_CODE,
+  ATTR_RESPONSES_ERROR_MESSAGE,
+  ATTR_RESPONSES_STREAMING,
   ATTR_SERVICE_NAME,
   ATTR_SESSION_ID,
   CHAT_ISOLATION_HEADER,
+  CLIENT_HEADER_PREFIX,
   INVOCATION_ID_HEADER,
   INVOCATION_ID_HEADERS,
   REQUEST_ID_HEADER,
   SESSION_ID_HEADER,
   SESSION_ID_HEADERS,
   USER_ISOLATION_HEADER,
+  addProtectedHeaders,
+  agentServerLoggingMiddleware,
+  agentServerRequestHeadersMiddleware,
   buildPlatformServerHeader,
   buildServerVersionSegment,
+  closeServerWithTimeout,
+  collectClientHeaders,
   configureAgentServerObservability,
+  configureExpressAgentServerApp,
   createErrorBody,
   createFoundryEnrichmentSpanProcessor,
+  defaultAgentServerLogger,
+  errorMiddleware,
   flushSpans,
+  formatError,
+  healthzHandler,
+  logAgentServerStartupConfiguration,
+  maskUri,
+  methodNotAllowed,
+  notFoundMiddleware,
+  readinessHandler,
   recordAgentServerSpanError,
+  resolveAgentIsolation,
   resolveAgentServerConfig,
   resolveGracefulShutdownTimeout,
   resolveInvocationIdentity,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-foundry-agentserver-core",
-  "version": "4.8.1",
+  "version": "4.9.0",
   "description": "Shared TypeScript host utilities for Foundry Agent Server protocol packages",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,7 +18,8 @@
   ],
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/context-async-hooks": "^2.6.0"
+    "@opentelemetry/context-async-hooks": "^2.6.0",
+    "express": "^5.0.0"
   },
   "optionalDependencies": {
     "@azure/monitor-opentelemetry": "^1.16.0",
@@ -28,6 +29,7 @@
     "@opentelemetry/sdk-trace-node": "^2.6.0"
   },
   "devDependencies": {
+    "@types/express": "^5.0.0",
     "@types/node": "^22.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.7.0",