effect 4.0.1 → 4.0.2

package/src/ai/LanguageModel.ts

@@ -869,12 +869,7 @@ export const make: (params: {
   > =>
     Effect.useSpan(
       "LanguageModel.generateText",
-      {
-        attributes: {
-          concurrency: options.concurrency,
-          toolChoice: options.toolChoice
-        }
-      },
+      { kind: "client" },
       Effect.fnUntraced(
         function*(span) {
           const spanTransformer = yield* getSpanTransformer
@@ -930,11 +925,8 @@ export const make: (params: {
     return Effect.useSpan(
       "LanguageModel.generateObject",
       {
-        attributes: {
-          objectName,
-          concurrency: options.concurrency,
-          toolChoice: options.toolChoice
-        }
+        kind: "client",
+        attributes: { "effect.ai.object_name": objectName }
       },
       Effect.fnUntraced(
         function*(span) {
@@ -1006,12 +998,7 @@ export const make: (params: {
       Tools extends Record<string, Tool.Any>,
       Options extends NoExcessProperties<GenerateTextOptions<Tools>, Options>
     >(options: Options & GenerateTextOptions<Tools>) {
-      const span = yield* Effect.makeSpanScoped("LanguageModel.streamText", {
-        attributes: {
-          concurrency: options.concurrency,
-          toolChoice: options.toolChoice
-        }
-      })
+      const span = yield* Effect.makeSpanScoped("LanguageModel.streamText", { kind: "client" })
 
       const providerOptions: Mutable<ProviderOptions> = {
         prompt: Prompt.make(options.prompt),
@@ -1083,7 +1070,7 @@ export const make: (params: {
     const tracker = Option.getOrUndefined(yield* Effect.serviceOption(ResponseIdTracker.ResponseIdTracker))
     const toolChoice = options.toolChoice ?? "auto"
     const concurrency = options.concurrency ?? "unbounded"
-    providerOptions.span.attribute("concurrency", concurrency)
+    annotateRequestOptions(providerOptions, toolChoice, concurrency)
 
     const generateWithNonIncrementalFallback = () => {
       const requestOptions: ProviderOptions = {
@@ -1336,7 +1323,7 @@ export const make: (params: {
     const tracker = Option.getOrUndefined(yield* Effect.serviceOption(ResponseIdTracker.ResponseIdTracker))
     const toolChoice = options.toolChoice ?? "auto"
     const concurrency = options.concurrency ?? "unbounded"
-    providerOptions.span.attribute("concurrency", concurrency)
+    annotateRequestOptions(providerOptions, toolChoice, concurrency)
 
     const streamWithNonIncrementalFallback = () => {
       const requestOptions: ProviderOptions = {
@@ -2485,6 +2472,16 @@ const resolveToolkit = <Tools extends Record<string, Tool.Any>, E, R>(
     ? toolkit
     : Effect.succeed(toolkit as unknown as Toolkit.WithHandler<Tools>)) as any
 
+const annotateRequestOptions = (
+  { responseFormat, span }: ProviderOptions,
+  toolChoice: ToolChoice<any>,
+  concurrency: Concurrency
+): void => {
+  span.attribute("gen_ai.output.type", responseFormat.type)
+  span.attribute("effect.ai.tool_choice", typeof toolChoice === "string" ? toolChoice : JSON.stringify(toolChoice))
+  span.attribute("effect.ai.concurrency", concurrency)
+}
+
 /**
  * @internal
  */

package/src/ai/McpServer.ts

@@ -654,6 +654,7 @@ const cancelledResponses = new WeakMap<object, string | number>()
 const requestKey = (requestId: string | number): string => `${typeof requestId}:${requestId}`
 
 interface ActiveRequest {
+  readonly requestId: RpcMessage.RequestId
   readonly prepared: McpRuntime.PreparedRequest
   readonly cancelled: boolean
 }
@@ -805,6 +806,7 @@ const runWithRuntime = Effect.fnUntraced(function*(
           payload: { requestId, reason }
         })
     })
+  let writeFromClient!: (clientId: number, message: RpcMessage.FromClientEncoded) => Effect.Effect<void>
   const handlers = yield* runtime.installHandlers({
     core: internalState.get(server)!.core,
     subscribeServerNotifications: PubSub.subscribe(serverNotifications),
@@ -976,8 +978,9 @@ const runWithRuntime = Effect.fnUntraced(function*(
       }
       return protocol.send(clientId, response)
     },
-    run: (f) =>
-      protocol.run((clientId, request_) => {
+    run: (f) => {
+      writeFromClient = f
+      return protocol.run((clientId, request_) => {
         const fiber = Fiber.getCurrent()!
         const request = request_ as unknown as
           | RpcMessage.FromServerEncoded
@@ -1045,11 +1048,13 @@ const runWithRuntime = Effect.fnUntraced(function*(
               if (httpRequest !== undefined && session !== undefined) {
                 appendPreResponseHandlerUnsafe(httpRequest, (_, res) =>
                   Effect.succeed(
-                    HttpServerResponse.setHeader(
-                      res,
-                      MCP_PROTOCOL_VERSION_HEADER,
-                      session.protocol.protocolVersion
-                    )
+                    runtime.resolveRequest(clientId, headers) === undefined
+                      ? HttpServerResponse.empty({ status: 404 })
+                      : HttpServerResponse.setHeader(
+                        res,
+                        MCP_PROTOCOL_VERSION_HEADER,
+                        session.protocol.protocolVersion
+                      )
                   ))
               }
               const routedRequest = runtime.routeClientRequest(selectedProtocol, request)
@@ -1130,7 +1135,11 @@ const runWithRuntime = Effect.fnUntraced(function*(
               }
               if (request.isNotification !== true) {
                 const requests = activeRequests.get(clientId) ?? new Map<string, ActiveRequest>()
-                requests.set(requestKey(request.id), { prepared, cancelled: false })
+                requests.set(requestKey(request.id), {
+                  requestId: RpcMessage.RequestId(request.id),
+                  prepared,
+                  cancelled: false
+                })
                 activeRequests.set(clientId, requests)
               }
               const handled = f(clientId, routedRequest)
@@ -1205,7 +1214,22 @@ const runWithRuntime = Effect.fnUntraced(function*(
           }
         }
       })
+    }
   })
+  if (isHttp) {
+    // Stop requests that can no longer receive client replies after termination.
+    yield* runtime.onSessionTerminated((binding) => {
+      const interrupts: Array<Effect.Effect<void>> = []
+      for (const [clientId, requests] of activeRequests) {
+        for (const { prepared, requestId } of requests.values()) {
+          if (prepared.binding === binding && cancelRequest(clientId, requestId)) {
+            interrupts.push(writeFromClient(clientId, { _tag: "Interrupt", requestId }))
+          }
+        }
+      }
+      return Effect.all(interrupts, { discard: true })
+    })
+  }
 
   const { notificationDelivery, notifications } = internalState.get(server)!
   yield* Effect.acquireRelease(
@@ -1526,19 +1550,28 @@ const mcpStdioSerialization = (
  * **Details**
  *
  * POST serves JSON-RPC and accepted notification-only requests return `202`.
- * Modern routing-header mismatches and unsupported protocol versions return
- * JSON-RPC errors with status `400`; unknown modern RPC methods return a
- * JSON-RPC method-not-found error with status `404`. Unsupported HTTP methods
- * return `405`. Requests carrying an `Origin` header are rejected unless the
- * exact origin appears in `allowedOrigins`; Origin-less non-browser clients
+ * Header mismatches, unsupported protocol versions, and invalid session-header
+ * usage return JSON-RPC errors with status `400`.
+ * Unknown modern RPC methods return a JSON-RPC method-not-found error with
+ * status `404`. Session requests without `MCP-Protocol-Version` use the version
+ * negotiated at initialization. Unsupported HTTP methods return `405`.
+ * Requests with an `Origin` header are rejected unless the exact origin
+ * appears in `allowedOrigins`; Origin-less non-browser clients
  * remain valid. The surrounding HTTP server remains responsible for binding
  * to an appropriate interface and installing authentication.
  *
+ * With `allowSessionTermination`, a DELETE carrying `Mcp-Session-Id` ends that
+ * session with `204` and interrupts its in-flight requests; later requests with
+ * that id get `404`. DELETE validates the session and `MCP-Protocol-Version`
+ * headers like POST. Without the option, or when only sessionless revisions
+ * such as `v2026_07_28` are configured, DELETE returns `405`. Any caller
+ * holding a session id can end that session, so authenticate requests in the
+ * surrounding router.
+ *
  * `layerHttp` always implements the single-endpoint Streamable HTTP topology.
  * Using `v2024_11_05` here is a custom compatibility transport for that
  * revision's schema. It does not implement the historical two-endpoint
- * HTTP+SSE transport, GET SSE, event resumption, session expiry, or client
- * session termination.
+ * HTTP+SSE transport, GET SSE, event resumption, or session expiry.
  *
  * @see {@link layerStdio} for exposing the server over stdio
  * @see {@link layer} for the base MCP server layer without a transport protocol
@@ -1558,24 +1591,10 @@ export const layerHttp = (options: {
   readonly protocols: Arr.NonEmptyReadonlyArray<McpProtocol.ProtocolAdapter>
   readonly extensions?: ServerExtensions | undefined
   readonly allowedOrigins?: ReadonlyArray<string> | undefined
+  readonly allowSessionTermination?: boolean | undefined
 }): Layer.Layer<McpServer | McpServerClient, Cause.IllegalArgumentError, HttpRouter.HttpRouter> => {
   const runtime = McpRuntime.layer(options.protocols)
-  const methodNotAllowedResponse = HttpServerResponse.empty({
-    status: 405,
-    headers: { allow: "POST" }
-  })
-  const methodNotAllowed = (request: HttpServerRequest.HttpServerRequest) =>
-    isAllowedMcpOrigin(request, options.allowedOrigins)
-      ? Effect.succeed(methodNotAllowedResponse)
-      : Effect.succeed(HttpServerResponse.empty({ status: 403 }))
-  const routes = Layer.mergeAll(
-    HttpRouter.add("GET", options.path, methodNotAllowed),
-    HttpRouter.add("PUT", options.path, methodNotAllowed),
-    HttpRouter.add("PATCH", options.path, methodNotAllowed),
-    HttpRouter.add("DELETE", options.path, methodNotAllowed),
-    HttpRouter.add("OPTIONS", options.path, methodNotAllowed)
-  )
-  return Layer.merge(layerWithRuntime(options, "http"), routes).pipe(
+  return layerWithRuntime(options, "http").pipe(
     Layer.provide(layerMcpProtocolHttp(options)),
     Layer.provide(runtime),
     Layer.provide(RpcSerialization.layerJsonRpc())
@@ -1585,6 +1604,7 @@ export const layerHttp = (options: {
 const layerMcpProtocolHttp = (options: {
   readonly path: HttpRouter.PathInput
   readonly allowedOrigins?: ReadonlyArray<string> | undefined
+  readonly allowSessionTermination?: boolean | undefined
 }): Layer.Layer<
   RpcServer.Protocol,
   never,
@@ -1596,6 +1616,29 @@ const layerMcpProtocolHttp = (options: {
       Effect.provideService(RpcSerialization.RpcSerialization, mcpHttpSerialization)
     )
     const router = yield* HttpRouter.HttpRouter
+    const allowSessionTermination = options.allowSessionTermination === true &&
+      runtime.protocols.some((protocol) => protocol.runtime._tag === "Stateful")
+    const forbidden = Effect.succeed(HttpServerResponse.empty({ status: 403 }))
+    const withAllowedOrigin = (
+      handler: (request: HttpServerRequest.HttpServerRequest) => Effect.Effect<HttpServerResponse.HttpServerResponse>
+    ) =>
+    (request: HttpServerRequest.HttpServerRequest) =>
+      isAllowedMcpOrigin(request, options.allowedOrigins) ? handler(request) : forbidden
+    const methodNotAllowedResponse = Effect.succeed(HttpServerResponse.empty({
+      status: 405,
+      headers: { allow: allowSessionTermination ? "POST, DELETE" : "POST" }
+    }))
+    const methodNotAllowed = withAllowedOrigin(() => methodNotAllowedResponse)
+    for (const method of ["GET", "PUT", "PATCH", "OPTIONS"] as const) {
+      yield* router.add(method, options.path, methodNotAllowed)
+    }
+    yield* router.add(
+      "DELETE",
+      options.path,
+      allowSessionTermination
+        ? withAllowedOrigin((request) => runtime.terminateHttpSession(request.headers))
+        : methodNotAllowed
+    )
     yield* router.add("POST", options.path, (request) => {
       if (!isAllowedMcpOrigin(request, options.allowedOrigins)) {
         return Effect.succeed(HttpServerResponse.empty({ status: 403 }))
@@ -1809,7 +1852,7 @@ export const registerToolkit: <Tools extends Record<string, Tool.Any>>(
 ) => Effect.Effect<
   void,
   never,
-  McpServer | Tool.HandlersFor<Tools> | Exclude<Tool.HandlerServices<Tools>, McpRequestContext>
+  McpServer | Tool.HandlersFor<Tools> | Exclude<Tool.HandlerServices<Tools[keyof Tools]>, McpRequestContext>
 > = Effect.fnUntraced(function*<Tools extends Record<string, Tool.Any>>(
   toolkit: Toolkit.Toolkit<Tools>
 ) {
@@ -1829,7 +1872,11 @@ export const registerToolkit: <Tools extends Record<string, Tool.Any>>(
     }
     return Context.makeUnsafe(services)
   }))
-  const services = omitRequestServices(yield* Effect.context<never>())
+  const services = omitRequestServices(
+    yield* Effect.context<
+      Exclude<Tool.HandlerServices<Tools[keyof Tools]>, McpRequestContext>
+    >()
+  )
   const reportCause = (cause: Cause.Cause<unknown>) => Effect.provideContext(ErrorReporter.report(cause), services)
   // Interruption propagates; anything else is logged, reported and scrubbed.
   const internalToolError = (cause: Cause.Cause<unknown>) => {
@@ -1973,7 +2020,7 @@ export const toolkit = <Tools extends Record<string, Tool.Any>>(
 ): Layer.Layer<
   never,
   never,
-  Tool.HandlersFor<Tools> | Exclude<Tool.HandlerServices<Tools>, McpRequestContext>
+  Tool.HandlersFor<Tools> | Exclude<Tool.HandlerServices<Tools[keyof Tools]>, McpRequestContext>
 > =>
   Layer.effectDiscard(registerToolkit(toolkit)).pipe(
     Layer.provide(McpServer.layer)
@@ -1997,6 +2044,19 @@ export type ValidateCompletions<Completions, Keys extends string> =
       : never
   }
 
+/**
+ * Utility type that collects the services required by the handlers of a
+ * completion-handler record, including handlers declared as optional.
+ *
+ * @stability unstable
+ * @category utility types
+ * @since 4.0.0
+ */
+export type CompletionServices<Completions> = {
+  [K in keyof Completions]-?: NonNullable<Completions[K]> extends (...args: any) => infer Ret ? Effect.Services<Ret>
+    : never
+}[keyof Completions]
+
 /**
  * Completion-handler map for a resource URI template.
  *
@@ -2374,7 +2434,13 @@ export const registerPrompt = <
 ): Effect.Effect<
   void,
   never,
-  Exclude<Schema.Struct.DecodingServices<Params> | R, McpRequestContext> | McpServer
+  | Exclude<
+    | Schema.Struct.DecodingServices<Params>
+    | R
+    | CompletionServices<Completions>,
+    McpRequestContext
+  >
+  | McpServer
 > => {
   const args = Arr.empty<PromptArgument>()
   const props: Record<string, Schema.Constraint> = options.parameters ?? {}
@@ -2512,7 +2578,12 @@ export const prompt = <
 ): Layer.Layer<
   never,
   never,
-  Exclude<Schema.Struct.DecodingServices<Params> | R, McpRequestContext>
+  Exclude<
+    | Schema.Struct.DecodingServices<Params>
+    | R
+    | CompletionServices<Completions>,
+    McpRequestContext
+  >
 > =>
   Layer.effectDiscard(registerPrompt(options)).pipe(
     Layer.provide(McpServer.layer)

package/src/ai/Telemetry.ts

@@ -27,50 +27,35 @@ import type * as Response from "./Response.ts"
  *
  * These attributes follow the OpenTelemetry generative AI semantic
  * conventions:
- * https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/
+ * https://github.com/open-telemetry/semantic-conventions-genai
  *
  * @stability unstable
  * @category models
  * @since 4.0.0
  */
 export type GenAITelemetryAttributes = Struct.Simplify<
-  & AttributesWithPrefix<BaseAttributes, "gen_ai">
+  & AttributesWithPrefix<ProviderAttributes, "gen_ai.provider">
   & AttributesWithPrefix<OperationAttributes, "gen_ai.operation">
-  & AttributesWithPrefix<TokenAttributes, "gen_ai.token">
+  & AttributesWithPrefix<OutputAttributes, "gen_ai.output">
   & AttributesWithPrefix<UsageAttributes, "gen_ai.usage">
   & AttributesWithPrefix<RequestAttributes, "gen_ai.request">
   & AttributesWithPrefix<ResponseAttributes, "gen_ai.response">
 >
 
-/**
- * All telemetry attributes which are part of the GenAI specification.
- *
- * @stability unstable
- * @category models
- * @since 4.0.0
- */
-export type AllAttributes =
-  & BaseAttributes
-  & OperationAttributes
-  & TokenAttributes
-  & UsageAttributes
-  & RequestAttributes
-  & ResponseAttributes
-
 /**
  * Telemetry attributes which are part of the GenAI specification and are
- * namespaced by `gen_ai`.
+ * namespaced by `gen_ai.provider`.
  *
  * @stability unstable
  * @category models
- * @since 4.0.0
+ * @since 4.0.2
  */
-export interface BaseAttributes {
+export interface ProviderAttributes {
   /**
-   * The Generative AI product as identified by the client or server
-   * instrumentation.
+   * The Generative AI provider as identified by the client or server
+   * instrumentation, written as `gen_ai.provider.name`.
    */
-  readonly system?: (string & {}) | WellKnownSystem | null | undefined
+  readonly name?: (string & {}) | WellKnownProviderName | null | undefined
 }
 
 /**
@@ -87,14 +72,17 @@ export interface OperationAttributes {
 
 /**
  * Telemetry attributes which are part of the GenAI specification and are
- * namespaced by `gen_ai.token`.
+ * namespaced by `gen_ai.output`.
  *
  * @stability unstable
  * @category models
- * @since 4.0.0
+ * @since 4.0.2
  */
-export interface TokenAttributes {
-  readonly type?: string | null | undefined
+export interface OutputAttributes {
+  /**
+   * The output modality requested by the client.
+   */
+  readonly type?: (string & {}) | WellKnownOutputType | null | undefined
 }
 
 /**
@@ -128,15 +116,15 @@ export interface RequestAttributes {
    */
   readonly temperature?: number | null | undefined
   /**
-   * The temperature setting for the GenAI request.
+   * The top_k sampling setting for the GenAI request.
    */
   readonly topK?: number | null | undefined
   /**
-   * The top_k sampling setting for the GenAI request.
+   * The top_p sampling setting for the GenAI request.
    */
   readonly topP?: number | null | undefined
   /**
-   * The top_p sampling setting for the GenAI request.
+   * The maximum number of tokens the model may generate.
    */
   readonly maxTokens?: number | null | undefined
   /**
@@ -203,7 +191,18 @@ export interface ResponseAttributes {
 export type WellKnownOperationName = "chat" | "embeddings" | "text_completion"
 
 /**
- * The `gen_ai.system` attribute has the following list of well-known values.
+ * The `gen_ai.output.type` attribute has the following list of well-known
+ * values.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.2
+ */
+export type WellKnownOutputType = "text" | "json" | "image" | "speech"
+
+/**
+ * The `gen_ai.provider.name` attribute has the following list of well-known
+ * values.
  *
  * **Details**
  *
@@ -212,23 +211,25 @@ export type WellKnownOperationName = "chat" | "embeddings" | "text_completion"
  *
  * @stability unstable
  * @category models
- * @since 4.0.0
+ * @since 4.0.2
  */
-export type WellKnownSystem =
+export type WellKnownProviderName =
   | "anthropic"
   | "aws.bedrock"
-  | "az.ai.inference"
-  | "az.ai.openai"
+  | "azure.ai.inference"
+  | "azure.ai.openai"
   | "cohere"
   | "deepseek"
-  | "gemini"
+  | "gcp.gemini"
+  | "gcp.gen_ai"
+  | "gcp.vertex_ai"
   | "groq"
   | "ibm.watsonx.ai"
   | "mistral_ai"
+  | "moonshot_ai"
   | "openai"
   | "perplexity"
-  | "vertex_ai"
-  | "xai"
+  | "x_ai"
 
 /**
  * Utility type for prefixing attribute names with a namespace.
@@ -375,11 +376,11 @@ export const addSpanAttributes = (
   }
 }
 
-const addSpanBaseAttributes = addSpanAttributes("gen_ai", String.camelToSnake)<BaseAttributes>
+const addSpanProviderAttributes = addSpanAttributes("gen_ai.provider", String.camelToSnake)<ProviderAttributes>
 const addSpanOperationAttributes = addSpanAttributes("gen_ai.operation", String.camelToSnake)<OperationAttributes>
+const addSpanOutputAttributes = addSpanAttributes("gen_ai.output", String.camelToSnake)<OutputAttributes>
 const addSpanRequestAttributes = addSpanAttributes("gen_ai.request", String.camelToSnake)<RequestAttributes>
 const addSpanResponseAttributes = addSpanAttributes("gen_ai.response", String.camelToSnake)<ResponseAttributes>
-const addSpanTokenAttributes = addSpanAttributes("gen_ai.token", String.camelToSnake)<TokenAttributes>
 const addSpanUsageAttributes = addSpanAttributes("gen_ai.usage", String.camelToSnake)<UsageAttributes>
 
 /**
@@ -387,8 +388,7 @@ const addSpanUsageAttributes = addSpanAttributes("gen_ai.usage", String.camelToS
  *
  * **Details**
  *
- * Combines base attributes with optional grouped attributes for comprehensive
- * telemetry coverage of AI operations.
+ * Groups attributes by their `gen_ai.*` namespace.
  *
  * **Example** (Configuring GenAI telemetry attributes)
  *
@@ -396,7 +396,7 @@ const addSpanUsageAttributes = addSpanAttributes("gen_ai.usage", String.camelToS
  * import type { Telemetry } from "effect/ai"
  *
  * const telemetryOptions: Telemetry.GenAITelemetryAttributeOptions = {
- *   system: "openai",
+ *   provider: { name: "openai" },
  *   operation: {
  *     name: "chat"
  *   },
@@ -416,18 +416,26 @@ const addSpanUsageAttributes = addSpanAttributes("gen_ai.usage", String.camelToS
  *   }
  * }
  *
- * const result = [telemetryOptions.system, telemetryOptions.usage?.inputTokens] // => ["openai", 50]
+ * const result = [telemetryOptions.provider?.name, telemetryOptions.usage?.inputTokens] // => ["openai", 50]
  * ```
  *
  * @stability unstable
  * @category options
  * @since 4.0.0
  */
-export type GenAITelemetryAttributeOptions = BaseAttributes & {
+export type GenAITelemetryAttributeOptions = {
+  /**
+   * Provider attributes (e.g., provider name).
+   */
+  readonly provider?: ProviderAttributes | undefined
   /**
    * Operation-specific attributes (e.g., operation name).
    */
   readonly operation?: OperationAttributes | undefined
+  /**
+   * Output attributes (e.g., requested output type).
+   */
+  readonly output?: OutputAttributes | undefined
   /**
    * Request-specific attributes (e.g., model parameters).
    */
@@ -436,10 +444,6 @@ export type GenAITelemetryAttributeOptions = BaseAttributes & {
    * Response-specific attributes (e.g., response metadata).
    */
   readonly response?: ResponseAttributes | undefined
-  /**
-   * Token-specific attributes.
-   */
-  readonly token?: TokenAttributes | undefined
   /**
    * Usage statistics attributes (e.g., token counts).
    */
@@ -451,7 +455,7 @@ export type GenAITelemetryAttributeOptions = BaseAttributes & {
  *
  * **When to use**
  *
- * Use when you need to write GenAI request, response, token, or usage
+ * Use when you need to write GenAI request, response, or usage
  * attributes onto an existing OpenTelemetry span.
  *
  * **Details**
@@ -473,7 +477,7 @@ export type GenAITelemetryAttributeOptions = BaseAttributes & {
  *   const span = yield* Effect.currentSpan
  *
  *   Telemetry.addGenAIAnnotations(span, {
- *     system: "openai",
+ *     provider: { name: "openai" },
  *     request: { model: "gpt-4", temperature: 0.7 },
  *     usage: { inputTokens: 100, outputTokens: 50 }
  *   })
@@ -493,7 +497,7 @@ export const addGenAIAnnotations: {
    *
    * **When to use**
    *
-   * Use when you need to write GenAI request, response, token, or usage
+   * Use when you need to write GenAI request, response, or usage
    * attributes onto an existing OpenTelemetry span.
    *
    * **Details**
@@ -515,7 +519,7 @@ export const addGenAIAnnotations: {
    *   const span = yield* Effect.currentSpan
    *
    *   Telemetry.addGenAIAnnotations(span, {
-   *     system: "openai",
+   *     provider: { name: "openai" },
    *     request: { model: "gpt-4", temperature: 0.7 },
    *     usage: { inputTokens: 100, outputTokens: 50 }
    *   })
@@ -535,7 +539,7 @@ export const addGenAIAnnotations: {
    *
    * **When to use**
    *
-   * Use when you need to write GenAI request, response, token, or usage
+   * Use when you need to write GenAI request, response, or usage
    * attributes onto an existing OpenTelemetry span.
    *
    * **Details**
@@ -557,7 +561,7 @@ export const addGenAIAnnotations: {
    *   const span = yield* Effect.currentSpan
    *
    *   Telemetry.addGenAIAnnotations(span, {
-   *     system: "openai",
+   *     provider: { name: "openai" },
    *     request: { model: "gpt-4", temperature: 0.7 },
    *     usage: { inputTokens: 100, outputTokens: 50 }
    *   })
@@ -573,11 +577,11 @@ export const addGenAIAnnotations: {
    */
   (span: Span, options: GenAITelemetryAttributeOptions): void
 } = dual(2, (span: Span, options: GenAITelemetryAttributeOptions) => {
-  addSpanBaseAttributes(span, { system: options.system })
+  if (Predicate.isNotNullish(options.provider)) addSpanProviderAttributes(span, options.provider)
   if (Predicate.isNotNullish(options.operation)) addSpanOperationAttributes(span, options.operation)
+  if (Predicate.isNotNullish(options.output)) addSpanOutputAttributes(span, options.output)
   if (Predicate.isNotNullish(options.request)) addSpanRequestAttributes(span, options.request)
   if (Predicate.isNotNullish(options.response)) addSpanResponseAttributes(span, options.response)
-  if (Predicate.isNotNullish(options.token)) addSpanTokenAttributes(span, options.token)
   if (Predicate.isNotNullish(options.usage)) addSpanUsageAttributes(span, options.usage)
 })