effect 4.0.0-beta.101 → 4.0.0-beta.103

package/src/unstable/ai/LanguageModel.ts

@@ -20,9 +20,9 @@ import type * as JsonSchema from "../../JsonSchema.ts"
 import * as Option from "../../Option.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Queue from "../../Queue.ts"
-import { CurrentConcurrency } from "../../References.ts"
 import * as Schema from "../../Schema.ts"
 import * as SchemaAST from "../../SchemaAST.ts"
+import * as Semaphore from "../../Semaphore.ts"
 import * as Sink from "../../Sink.ts"
 import * as Stream from "../../Stream.ts"
 import type { Span } from "../../Tracer.ts"
@@ -52,10 +52,22 @@ import * as Toolkit from "./Toolkit.ts"
  *
  * **Example** (Accessing the language model service)
  *
- * ```ts
- * import { Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Layer, Stream } from "effect"
  * import { LanguageModel } from "effect/unstable/ai"
  *
+ * const FakeLanguageModel = Layer.effect(
+ *   LanguageModel.LanguageModel,
+ *   LanguageModel.make({
+ *     generateText: () =>
+ *       Effect.succeed([{
+ *         type: "text",
+ *         text: "Machine learning finds patterns in data."
+ *       }]),
+ *     streamText: () => Stream.empty
+ *   })
+ * )
+ *
  * const program = Effect.gen(function*() {
  *   const model = yield* LanguageModel.LanguageModel
  *   const response = yield* model.generateText({
@@ -63,6 +75,8 @@ import * as Toolkit from "./Toolkit.ts"
  *   })
  *   return response.text
  * })
+ *
+ * await Effect.runPromise(program.pipe(Effect.provide(FakeLanguageModel))) // => "Machine learning finds patterns in data."
  * ```
  *
  * @category services
@@ -186,9 +200,12 @@ export interface Service {
  *
  * Different language model providers have varying constraints on the JSON
  * schemas they accept. A `CodecTransformer` rewrites a codec's encoded side to
- * satisfy those constraints while preserving the decoded type.
+ * satisfy those constraints while preserving the decoded type. A provider
+ * schema may be less restrictive than the codec when the provider cannot
+ * express every constraint; the returned codec remains authoritative for
+ * validating model output.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type CodecTransformer = <T, E, RD, RE>(schema: Schema.ConstraintCodec<T, E, RD, RE>) => {
@@ -334,21 +351,14 @@ export type ToolChoice<ToolName extends string> =
  *
  * **Example** (Inspecting a text response)
  *
- * ```ts
- * import { Effect } from "effect"
- * import { LanguageModel } from "effect/unstable/ai"
+ * ```ts import.meta.vitest
+ * import { LanguageModel, Response } from "effect/unstable/ai"
  *
- * const program = Effect.gen(function*() {
- *   const response = yield* LanguageModel.generateText({
- *     prompt: "Explain photosynthesis"
- *   })
+ * const response = new LanguageModel.GenerateTextResponse([
+ *   Response.makePart("text", { text: "Plants convert light into energy." })
+ * ])
  *
- *   console.log(response.text) // Generated text content
- *   console.log(response.finishReason) // "stop", "length", etc.
- *   console.log(response.usage) // Usage information
- *
- *   return response
- * })
+ * const result = [response.text, response.finishReason] // => ["Plants convert light into energy.", "unknown"]
  * ```
  *
  * @category models
@@ -445,26 +455,16 @@ export class GenerateTextResponse<Tools extends Record<string, Tool.Any>> {
  *
  * **Example** (Inspecting an object response)
  *
- * ```ts
- * import { Effect, Schema } from "effect"
- * import { LanguageModel } from "effect/unstable/ai"
- *
- * const UserSchema = Schema.Struct({
- *   name: Schema.String,
- *   email: Schema.String
- * })
- *
- * const program = Effect.gen(function*() {
- *   const response = yield* LanguageModel.generateObject({
- *     prompt: "Create user: John Doe, john@example.com",
- *     schema: UserSchema
- *   })
+ * ```ts import.meta.vitest
+ * import { LanguageModel, Response } from "effect/unstable/ai"
  *
- *   console.log(response.value) // { name: "John Doe", email: "john@example.com" }
- *   console.log(response.text) // Raw generated text
+ * const response = new LanguageModel.GenerateObjectResponse(
+ *   { name: "John Doe", email: "john@example.com" },
+ *   [Response.makePart("text", { text: '{"name":"John Doe","email":"john@example.com"}' })]
+ * )
  *
- *   return response.value
- * })
+ * response.value // => { name: "John Doe", email: "john@example.com" }
+ * response.text // => '{"name":"John Doe","email":"john@example.com"}'
  * ```
  *
  * @category models
@@ -1004,6 +1004,8 @@ 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)
 
     const generateWithNonIncrementalFallback = () => {
       const requestOptions: ProviderOptions = {
@@ -1121,7 +1123,7 @@ export const make: (params: {
       const approvedResults = yield* executeApprovedToolCalls(
         approved,
         toolkit,
-        options.concurrency
+        concurrency
       )
       const deniedResults = createDenialResults(denied)
       const preResolvedResults = [...approvedResults, ...deniedResults]
@@ -1189,7 +1191,7 @@ export const make: (params: {
       rawContent,
       toolkit,
       providerOptions.prompt.content,
-      options.concurrency
+      concurrency
     ).pipe(
       Stream.filter(
         (result) =>
@@ -1239,6 +1241,8 @@ 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)
 
     const streamWithNonIncrementalFallback = () => {
       const requestOptions: ProviderOptions = {
@@ -1379,7 +1383,7 @@ export const make: (params: {
       const approvedResults = yield* executeApprovedToolCalls(
         pendingApproved,
         toolkit,
-        options.concurrency
+        concurrency
       )
       const deniedResults = createDenialResults(pendingDenied)
       const preResolvedResults = [...approvedResults, ...deniedResults]
@@ -1486,6 +1490,9 @@ export const make: (params: {
 
     // FiberSet to track concurrent tool call handlers
     const toolCallFibers = yield* FiberSet.make<void, AiError.AiError>()
+    const toolCallSemaphore = concurrency === "unbounded"
+      ? undefined
+      : yield* Semaphore.make(concurrency)
 
     // Helper function to handle tool calls with approval logic
     const handleToolCall = Effect.fnUntraced(function*(part: Response.ToolCallPartEncoded) {
@@ -1509,7 +1516,7 @@ export const make: (params: {
         return
       }
 
-      yield* toolkit.handle(part.name, part.params as any).pipe(
+      yield* toolkit.handle(part.name, part.params as any, part.id).pipe(
         Stream.unwrap,
         Stream.runForEach((result) => {
           const toolResultPart = Response.makePart("tool-result", {
@@ -1550,7 +1557,11 @@ export const make: (params: {
           // Fork tool call handlers - use the raw chunk for encoded params
           for (const part of chunk) {
             if (part.type === "tool-call" && part.providerExecuted !== true) {
-              yield* FiberSet.run(toolCallFibers, handleToolCall(part))
+              const effect = handleToolCall(part)
+              yield* FiberSet.run(
+                toolCallFibers,
+                toolCallSemaphore ? toolCallSemaphore.withPermit(effect) : effect
+              )
             }
           }
         })
@@ -1592,21 +1603,43 @@ export const make: (params: {
  *
  * **Example** (Generating text with options)
  *
- * ```ts
- * import { Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Layer, Stream } from "effect"
  * import { LanguageModel } from "effect/unstable/ai"
  *
- * const program = Effect.gen(function*() {
- *   const response = yield* LanguageModel.generateText({
- *     prompt: "Write a haiku about programming",
- *     toolChoice: "none"
+ * const FakeLanguageModel = Layer.effect(
+ *   LanguageModel.LanguageModel,
+ *   LanguageModel.make({
+ *     generateText: (options) =>
+ *       Effect.succeed([
+ *         {
+ *           type: "text",
+ *           text: options.toolChoice === "none"
+ *             ? "Code flows through types / Errors become values / Programs stay composed"
+ *             : "Unexpected tool choice"
+ *         },
+ *         {
+ *           type: "finish",
+ *           reason: "stop",
+ *           usage: {
+ *             inputTokens: { total: 6 },
+ *             outputTokens: { total: 12 }
+ *           }
+ *         }
+ *       ]),
+ *     streamText: () => Stream.empty
  *   })
+ * )
  *
- *   console.log(response.text)
- *   console.log(response.usage.inputTokens.total)
+ * const program = LanguageModel.generateText({
+ *   prompt: "Write a haiku about programming",
+ *   toolChoice: "none"
+ * }).pipe(
+ *   Effect.map((response) => [response.text, response.usage.inputTokens.total]),
+ *   Effect.provide(FakeLanguageModel)
+ * )
  *
- *   return response
- * })
+ * await Effect.runPromise(program) // => ["Code flows through types / Errors become values / Programs stay composed", 6]
  * ```
  *
  * @category text generation
@@ -1661,8 +1694,8 @@ export const generateText: {
  *
  * **Example** (Generating an object)
  *
- * ```ts
- * import { Effect, Schema } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Layer, Schema, Stream } from "effect"
  * import { LanguageModel } from "effect/unstable/ai"
  *
  * const EventSchema = Schema.Struct({
@@ -1671,22 +1704,31 @@ export const generateText: {
  *   location: Schema.String
  * })
  *
- * const program = Effect.gen(function*() {
- *   const response = yield* LanguageModel.generateObject({
- *     prompt:
- *       "Extract event info: Tech Conference on March 15th in San Francisco",
- *     schema: EventSchema,
- *     objectName: "event"
+ * const FakeLanguageModel = Layer.effect(
+ *   LanguageModel.LanguageModel,
+ *   LanguageModel.make({
+ *     generateText: () =>
+ *       Effect.succeed([{
+ *         type: "text",
+ *         text: '{"title":"Tech Conference","date":"March 15th","location":"San Francisco"}'
+ *       }]),
+ *     streamText: () => Stream.empty
  *   })
- *
- *   console.log(response.value)
- *   // { title: "Tech Conference", date: "March 15th", location: "San Francisco" }
- *
- *   return response.value
- * })
+ * )
+ *
+ * const program = LanguageModel.generateObject({
+ *   prompt: "Extract event info: Tech Conference on March 15th in San Francisco",
+ *   schema: EventSchema,
+ *   objectName: "event"
+ * }).pipe(
+ *   Effect.map((response) => response.value),
+ *   Effect.provide(FakeLanguageModel)
+ * )
+ *
+ * await Effect.runPromise(program) // => { title: "Tech Conference", date: "March 15th", location: "San Francisco" }
  * ```
  *
- * @category object generation
+ * @category generators
  * @since 4.0.0
  */
 export const generateObject = <
@@ -1718,18 +1760,30 @@ export const generateObject = <
  *
  * **Example** (Streaming text deltas)
  *
- * ```ts
- * import { Console, Effect, Stream } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Layer, Stream } from "effect"
  * import { LanguageModel } from "effect/unstable/ai"
  *
+ * const FakeLanguageModel = Layer.effect(
+ *   LanguageModel.LanguageModel,
+ *   LanguageModel.make({
+ *     generateText: () => Effect.succeed([]),
+ *     streamText: () =>
+ *       Stream.make(
+ *         { type: "text-delta", id: "story", delta: "The explorer reached orbit." },
+ *         { type: "text-delta", id: "story", delta: " Earth glowed below." }
+ *       )
+ *   })
+ * )
+ *
  * const program = LanguageModel.streamText({
  *   prompt: "Write a story about a space explorer"
- * }).pipe(Stream.runForEach((part) => {
- *   if (part.type === "text-delta") {
- *     return Console.log(part.delta)
- *   }
- *   return Effect.void
- * }))
+ * }).pipe(
+ *   Stream.runFold(() => "", (text, part) => part.type === "text-delta" ? text + part.delta : text),
+ *   Effect.provide(FakeLanguageModel)
+ * )
+ *
+ * await Effect.runPromise(program) // => "The explorer reached orbit. Earth glowed below."
  * ```
  *
  * @category text generation
@@ -1954,7 +2008,7 @@ const isApprovalNeeded = Effect.fnUntraced(function*<T extends Tool.Any>(
 const executeApprovedToolCalls = <Tools extends Record<string, Tool.Any>>(
   approvals: ReadonlyArray<ApprovalResult>,
   toolkit: Toolkit.WithHandler<Tools>,
-  concurrency: Concurrency | undefined
+  concurrency: Concurrency
 ): Effect.Effect<
   Array<Prompt.ToolResultPart>,
   Tool.HandlerError<Tools[keyof Tools]> | AiError.AiError,
@@ -1982,7 +2036,8 @@ const executeApprovedToolCalls = <Tools extends Record<string, Tool.Any>>(
 
     const resultStream = yield* toolkit.handle(
       toolCall.name,
-      toolCall.params as any
+      toolCall.params as any,
+      approval.toolCallId
     )
 
     const terminalResult = yield* resultStream.pipe(
@@ -2004,14 +2059,8 @@ const executeApprovedToolCalls = <Tools extends Record<string, Tool.Any>>(
     })
   })
 
-  return Effect.gen(function*() {
-    const resolveConcurrency = concurrency === "inherit"
-      ? yield* Effect.service(CurrentConcurrency)
-      : (concurrency ?? "unbounded")
-
-    return yield* Effect.forEach(approvals, executeTool, {
-      concurrency: resolveConcurrency
-    })
+  return Effect.forEach(approvals, executeTool, {
+    concurrency
   })
 }
 
@@ -2050,7 +2099,7 @@ const resolveToolCalls = <Tools extends Record<string, Tool.Any>>(
   content: ReadonlyArray<Response.AllPartsEncoded>,
   toolkit: Toolkit.WithHandler<Tools>,
   messages: ReadonlyArray<Prompt.Message>,
-  concurrency: Concurrency | undefined
+  concurrency: Concurrency
 ): Stream.Stream<
   ToolResolutionResult<Tools>,
   Tool.HandlerError<Tools[keyof Tools]> | AiError.AiError,
@@ -2098,7 +2147,7 @@ const resolveToolCalls = <Tools extends Record<string, Tool.Any>>(
       }
 
       if (approvedToolCallIds.has(toolCall.id)) {
-        return toolkit.handle(toolCall.name, toolCall.params as any).pipe(
+        return toolkit.handle(toolCall.name, toolCall.params as any, toolCall.id).pipe(
           Stream.unwrap,
           Stream.map(
             (result) =>
@@ -2124,7 +2173,7 @@ const resolveToolCalls = <Tools extends Record<string, Tool.Any>>(
         )
       }
 
-      return toolkit.handle(toolCall.name, toolCall.params as any).pipe(
+      return toolkit.handle(toolCall.name, toolCall.params as any, toolCall.id).pipe(
         Stream.unwrap,
         Stream.map(
           (result) =>
@@ -2139,14 +2188,7 @@ const resolveToolCalls = <Tools extends Record<string, Tool.Any>>(
     }).pipe(Stream.unwrap)
   )
 
-  const resolveConcurrency = concurrency === "inherit"
-    ? Effect.service(CurrentConcurrency)
-    : Effect.succeed(concurrency ?? "unbounded")
-
-  return resolveConcurrency.pipe(
-    Effect.map((concurrency) => Stream.mergeAll(streams, { concurrency })),
-    Stream.unwrap
-  )
+  return Stream.mergeAll(streams, { concurrency })
 }
 
 // =============================================================================

package/src/unstable/ai/McpProtocol.ts

@@ -0,0 +1,48 @@
+/**
+ * Defines the MCP protocol implementations that an `McpServer` can support.
+ *
+ * @since 4.0.0
+ */
+import type * as RpcGroup from "../rpc/RpcGroup.ts"
+import * as Internal from "./internal/mcpProtocol.ts"
+import * as McpSchema from "./McpSchema.ts"
+
+/**
+ * The MCP 2025-06-18 protocol implementation.
+ *
+ * @category protocols
+ * @since 4.0.0
+ */
+export const v2025_06_18: ProtocolAdapter = Internal.make({
+  protocolVersion: "2025-06-18",
+  transport: {
+    acceptsJsonRpcBatches: false,
+    requiresVersionHeader: true
+  },
+  clientRpcs: McpSchema.ClientRpcs,
+  clientNotificationRpcs: McpSchema.ClientNotificationRpcs,
+  serverRequestRpcs: McpSchema.ServerRequestRpcs,
+  serverNotificationRpcs: McpSchema.ServerNotificationRpcs
+})
+
+/**
+ * An implemented MCP protocol that can be supplied to `McpServer`.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type ProtocolAdapter = Internal.ProtocolAdapter<
+  "2025-06-18",
+  RpcGroup.Rpcs<typeof McpSchema.ClientRpcs>,
+  RpcGroup.Rpcs<typeof McpSchema.ClientNotificationRpcs>,
+  RpcGroup.Rpcs<typeof McpSchema.ServerRequestRpcs>,
+  RpcGroup.Rpcs<typeof McpSchema.ServerNotificationRpcs>
+>
+
+/**
+ * The MCP protocol versions implemented by this release.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type ProtocolVersion = ProtocolAdapter["protocolVersion"]