effect 4.0.0-beta.4 → 4.0.0-beta.40

package/src/unstable/ai/LanguageModel.ts

@@ -51,7 +51,7 @@
 import type * as Cause from "../../Cause.ts"
 import * as Effect from "../../Effect.ts"
 import * as FiberSet from "../../FiberSet.ts"
-import { constFalse } from "../../Function.ts"
+import { constFalse, identity, pipe } from "../../Function.ts"
 import type * as JsonSchema from "../../JsonSchema.ts"
 import * as Option from "../../Option.ts"
 import * as Predicate from "../../Predicate.ts"
@@ -69,6 +69,7 @@ import { defaultIdGenerator, IdGenerator } from "./IdGenerator.ts"
 import * as InternalCodecTransformer from "./internal/codec-transformer.ts"
 import * as Prompt from "./Prompt.ts"
 import * as Response from "./Response.ts"
+import * as ResponseIdTracker from "./ResponseIdTracker.ts"
 import type { SpanTransformer } from "./Telemetry.ts"
 import { CurrentSpanTransformer } from "./Telemetry.ts"
 import type * as Tool from "./Tool.ts"
@@ -135,7 +136,7 @@ export interface Service {
    */
   readonly generateObject: <
     ObjectEncoded extends Record<string, any>,
-    StructuredOutputSchema extends Schema.Codec<any, ObjectEncoded, any, any>,
+    StructuredOutputSchema extends Schema.Encoder<ObjectEncoded, unknown>,
     Options extends NoExcessProperties<
       GenerateObjectOptions<any, StructuredOutputSchema>,
       Options
@@ -180,22 +181,6 @@ export type CodecTransformer = <T, E, RD, RE>(schema: Schema.Codec<T, E, RD, RE>
   readonly jsonSchema: JsonSchema.JsonSchema
 }
 
-/**
- * A `ServiceMap.Reference` that holds the current `CodecTransformer` used by
- * `LanguageModel.generateObject` to adapt structured output schemas for the
- * active provider.
- *
- * By default, this is the identity function (no transformation). Provider
- * packages (e.g. `@effect/ai-anthropic`) override this reference with a
- * provider-specific transformer so that schemas are automatically rewritten
- * before being sent to the model as well as before decoding the generated value.
- *
- * @since 4.0.0
- * @category services
- */
-export const CurrentCodecTransformer: ServiceMap.Reference<CodecTransformer> =
-  InternalCodecTransformer.CurrentCodecTransformer
-
 /**
  * The default codec transformer that passes schemas through without
  * provider-specific rewrites.
@@ -221,15 +206,7 @@ export interface GenerateTextOptions<Tools extends Record<string, Tool.Any>> {
    * A toolkit containing both the tools and the tool call handler to use to
    * augment text generation.
    */
-  readonly toolkit?:
-    | Toolkit.WithHandler<Tools>
-    | Effect.Yieldable<
-      Toolkit.Toolkit<Tools>,
-      Toolkit.WithHandler<Tools>,
-      never,
-      any
-    >
-    | undefined
+  readonly toolkit?: ToolkitOption<Tools> | undefined
 
   /**
    * The tool choice mode for the language model.
@@ -483,6 +460,89 @@ export class GenerateObjectResponse<
 // Utility Types
 // =============================================================================
 
+/**
+ * The supported toolkit option shapes for language model operations.
+ *
+ * @since 4.0.0
+ * @category utility types
+ */
+export type ToolkitOption<
+  Tools extends Record<string, Tool.Any>,
+  E = never,
+  R = any
+> = Tools extends any ? (
+    | Toolkit.WithHandler<Tools>
+    | Effect.Yieldable<
+      Toolkit.Toolkit<Tools>,
+      Toolkit.WithHandler<Tools>,
+      E,
+      R
+    >
+  )
+  : never
+
+type ExtractToolsFromToolkitOption<ToolkitValue> = ToolkitValue extends Toolkit.WithHandler<infer Tools> ? Tools
+  : ToolkitValue extends Effect.Yieldable<
+    Toolkit.Toolkit<infer Tools>,
+    Toolkit.WithHandler<infer _Tools>,
+    infer _E,
+    infer _R
+  > ? Tools
+  : never
+
+/**
+ * Utility type that extracts the toolset from LanguageModel options.
+ *
+ * @since 4.0.0
+ * @category utility types
+ */
+export type ExtractTools<Options> = Options extends {
+  readonly toolkit: infer ToolkitValue
+} ? ExtractToolsFromToolkitOption<Exclude<ToolkitValue, undefined>>
+  : {}
+
+type ExtractErrorFromToolkitOption<ToolkitValue, DisableToolCallResolution extends boolean> = ToolkitValue extends
+  Toolkit.WithHandler<infer Tools> ?
+    | AiError.AiError
+    | (DisableToolCallResolution extends true ? never : Tool.HandlerError<Tools[keyof Tools]>)
+  : ToolkitValue extends Effect.Yieldable<
+    Toolkit.Toolkit<infer Tools>,
+    Toolkit.WithHandler<infer _Tools>,
+    infer E,
+    infer _R
+  > ? AiError.AiError | E | (DisableToolCallResolution extends true ? never : Tool.HandlerError<Tools[keyof Tools]>)
+  : AiError.AiError
+
+type ExtractServicesFromToolkitOption<ToolkitValue> = ToolkitValue extends Toolkit.WithHandler<infer Tools> ?
+    | Tool.HandlerServices<Tools[keyof Tools]>
+    | Tool.ResultDecodingServices<Tools[keyof Tools]>
+  : ToolkitValue extends Effect.Yieldable<
+    Toolkit.Toolkit<infer Tools>,
+    Toolkit.WithHandler<infer _Tools>,
+    infer _E,
+    infer R
+  > ?
+      | Tool.HandlerServices<Tools[keyof Tools]>
+      | Tool.ResultDecodingServices<Tools[keyof Tools]>
+      | R
+  : never
+
+type ExtractToolkitResolutionError<ToolkitValue> = ToolkitValue extends Effect.Yieldable<
+  Toolkit.Toolkit<infer _Tools>,
+  Toolkit.WithHandler<infer _Tools>,
+  infer E,
+  infer _R
+> ? E
+  : never
+
+type ExtractToolkitResolutionServices<ToolkitValue> = ToolkitValue extends Effect.Yieldable<
+  Toolkit.Toolkit<infer _Tools>,
+  Toolkit.WithHandler<infer _Tools>,
+  infer _E,
+  infer R
+> ? R
+  : never
+
 /**
  * Utility type that extracts the error type from LanguageModel options.
  *
@@ -493,29 +553,15 @@ export class GenerateObjectResponse<
  * @category utility types
  */
 export type ExtractError<Options> = Options extends {
-  readonly toolkit: Toolkit.WithHandler<infer _Tools>
   readonly disableToolCallResolution: true
-} ? AiError.AiError
-  : Options extends {
-    readonly toolkit: Effect.Yieldable<
-      Toolkit.Toolkit<infer _Tools>,
-      Toolkit.WithHandler<infer _Tools>,
-      infer _E,
-      infer _R
-    >
-    readonly disableToolCallResolution: true
-  } ? AiError.AiError | _E
+  readonly toolkit: infer ToolkitValue
+} ? ExtractErrorFromToolkitOption<Exclude<ToolkitValue, undefined>, true>
   : Options extends {
-    readonly toolkit: Toolkit.WithHandler<infer _Tools>
-  } ? AiError.AiError | Tool.HandlerError<_Tools[keyof _Tools]>
+    readonly toolkit: infer ToolkitValue
+  } ? ExtractErrorFromToolkitOption<Exclude<ToolkitValue, undefined>, false>
   : Options extends {
-    readonly toolkit: Effect.Yieldable<
-      Toolkit.Toolkit<infer _Tools>,
-      Toolkit.WithHandler<infer _Tools>,
-      infer _E,
-      infer _R
-    >
-  } ? AiError.AiError | Tool.HandlerError<_Tools[keyof _Tools]> | _E
+    readonly disableToolCallResolution: true
+  } ? AiError.AiError
   : AiError.AiError
 
 /**
@@ -527,27 +573,11 @@ export type ExtractError<Options> = Options extends {
  * @category utility types
  */
 export type ExtractServices<Options> = Options extends {
-  readonly toolkit: Toolkit.WithHandler<infer _Tools>
-}
-  // Required for tool call execution
-  ?
-    | Tool.ResultEncodingServices<_Tools[keyof _Tools]>
-    // Required for decoding large language model responses
-    | Tool.ResultDecodingServices<_Tools[keyof _Tools]>
+  readonly disableToolCallResolution: true
+} ? never
   : Options extends {
-    readonly toolkit: Effect.Yieldable<
-      Toolkit.Toolkit<infer _Tools>,
-      Toolkit.WithHandler<infer _Tools>,
-      infer _E,
-      infer _R
-    >
-  }
-  // Required for tool call execution
-    ?
-      | Tool.ResultEncodingServices<_Tools[keyof _Tools]>
-      // Required for decoding large language model responses
-      | Tool.ResultDecodingServices<_Tools[keyof _Tools]>
-      | _R
+    readonly toolkit: infer Toolkit
+  } ? ExtractServicesFromToolkitOption<Exclude<Toolkit, undefined>>
   : never
 
 // =============================================================================
@@ -619,15 +649,28 @@ export interface ProviderOptions {
    * The span to use to trace interactions with the large language model.
    */
   readonly span: Span
+
+  /**
+   * The previous response identifier for incremental provider calls.
+   */
+  readonly previousResponseId: string | undefined
+
+  /**
+   * The prompt reduced to messages not yet seen by the provider.
+   */
+  readonly incrementalPrompt: Prompt.Prompt | undefined
 }
 
 /**
- * Parameters required to construct a LanguageModel service.
+ * Creates a LanguageModel service from provider-specific implementations.
+ *
+ * This constructor takes provider-specific implementations for text generation
+ * and streaming text generation and returns a LanguageModel service.
  *
  * @since 4.0.0
- * @category models
+ * @category constructors
  */
-export interface ConstructorParams {
+export const make: (params: {
   /**
    * A method which requests text generation from the large language model
    * provider.
@@ -648,19 +691,14 @@ export interface ConstructorParams {
   readonly streamText: (
     options: ProviderOptions
   ) => Stream.Stream<Response.StreamPartEncoded, AiError.AiError, IdGenerator>
-}
 
-/**
- * Creates a LanguageModel service from provider-specific implementations.
- *
- * This constructor takes provider-specific implementations for text generation
- * and streaming text generation and returns a LanguageModel service.
- *
- * @since 4.0.0
- * @category constructors
- */
-export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effect.fnUntraced(function*(params) {
-  const codecTransformer = yield* InternalCodecTransformer.CurrentCodecTransformer
+  /**
+   * A function that transforms a `Schema.Codec` into a provider-compatible form
+   * for structured output generation.
+   */
+  readonly codecTransformer?: CodecTransformer | undefined
+}) => Effect.Effect<Service> = Effect.fnUntraced(function*(params) {
+  const codecTransformer = params.codecTransformer ?? defaultCodecTransformer
 
   const parentSpanTransformer = yield* Effect.serviceOption(
     CurrentSpanTransformer
@@ -700,7 +738,9 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
             tools: [],
             toolChoice: "none",
             responseFormat: { type: "text" },
-            span
+            span,
+            previousResponseId: undefined,
+            incrementalPrompt: undefined
           }
           const content = yield* generateContent(options, providerOptions)
 
@@ -721,14 +761,13 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
             })
           )),
         (effect, span) => Effect.withParentSpan(effect, span, { captureStackTrace: false }),
-        Effect.provideService(IdGenerator, idGenerator),
-        Effect.provideService(InternalCodecTransformer.CurrentCodecTransformer, codecTransformer)
+        Effect.provideService(IdGenerator, idGenerator)
       )
     ) as any
 
   const generateObject = <
     ObjectEncoded extends Record<string, any>,
-    StructuredOutputSchema extends Schema.Codec<any, ObjectEncoded, any, any>,
+    StructuredOutputSchema extends Schema.Encoder<ObjectEncoded, unknown>,
     Options extends NoExcessProperties<
       GenerateObjectOptions<any, StructuredOutputSchema>,
       Options
@@ -764,7 +803,9 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
               objectName,
               schema: options.schema
             },
-            span
+            span,
+            previousResponseId: undefined,
+            incrementalPrompt: undefined
           }
 
           const content = yield* generateContent(options, providerOptions)
@@ -800,8 +841,7 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
             })
           )),
         (effect, span) => Effect.withParentSpan(effect, span, { captureStackTrace: false }),
-        Effect.provideService(IdGenerator, idGenerator),
-        Effect.provideService(InternalCodecTransformer.CurrentCodecTransformer, codecTransformer)
+        Effect.provideService(IdGenerator, idGenerator)
       )
     ) as any
   }
@@ -832,7 +872,9 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
         tools: [],
         toolChoice: "none",
         responseFormat: { type: "text" },
-        span
+        span,
+        previousResponseId: undefined,
+        incrementalPrompt: undefined
       }
 
       // Resolve the content stream for the request
@@ -872,8 +914,7 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
         })
         : error
     ),
-    Stream.provideService(IdGenerator, idGenerator),
-    Stream.provideService(InternalCodecTransformer.CurrentCodecTransformer, codecTransformer)
+    Stream.provideService(IdGenerator, idGenerator)
   ) as any
 
   const generateContent: <
@@ -893,8 +934,27 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
     options: Options & GenerateTextOptions<Tools>,
     providerOptions: Mutable<ProviderOptions>
   ) {
+    const tracker = Option.getOrUndefined(yield* Effect.serviceOption(ResponseIdTracker.ResponseIdTracker))
     const toolChoice = options.toolChoice ?? "auto"
 
+    const generateWithNonIncrementalFallback = () => {
+      const requestOptions: ProviderOptions = {
+        ...providerOptions
+      }
+      const fallbackPrompt = requestOptions.prompt
+      const fallbackOptions: ProviderOptions = {
+        ...requestOptions,
+        prompt: fallbackPrompt,
+        incrementalPrompt: undefined,
+        previousResponseId: undefined
+      }
+      return requestOptions.incrementalPrompt
+        ? params.generateText(requestOptions).pipe(
+          Effect.catchReason("AiError", "InvalidRequestError", (_) => params.generateText(fallbackOptions))
+        )
+        : params.generateText(requestOptions)
+    }
+
     // Check for pending approvals that need resolution
     const { approved, denied } = collectToolApprovals(
       providerOptions.prompt.content,
@@ -916,11 +976,24 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
           })
         })
       }
+      if (tracker) {
+        const prepared = tracker.prepareUnsafe(providerOptions.prompt)
+        if (Option.isSome(prepared)) {
+          providerOptions.previousResponseId = prepared.value.previousResponseId
+          providerOptions.incrementalPrompt = prepared.value.prompt
+        }
+      }
       const ResponseSchema = Schema.mutable(
         Schema.Array(Response.Part(Toolkit.empty))
       )
-      const rawContent = yield* params.generateText(providerOptions)
+      const rawContent = yield* generateWithNonIncrementalFallback()
       const content = yield* Schema.decodeEffect(ResponseSchema)(rawContent)
+      if (tracker) {
+        const responseMetadata = content.find((part) => part.type === "response-metadata")
+        if (Predicate.isNotUndefined(responseMetadata) && Predicate.isNotUndefined(responseMetadata.id)) {
+          tracker.markParts(providerOptions.prompt.content, responseMetadata.id)
+        }
+      }
       return content as Array<Response.Part<Tools>>
     }
 
@@ -941,17 +1014,29 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
           })
         })
       }
+      if (tracker) {
+        const prepared = tracker.prepareUnsafe(providerOptions.prompt)
+        if (Option.isSome(prepared)) {
+          providerOptions.previousResponseId = prepared.value.previousResponseId
+          providerOptions.incrementalPrompt = prepared.value.prompt
+        }
+      }
       const ResponseSchema = Schema.mutable(
         Schema.Array(Response.Part(Toolkit.empty))
       )
-      const rawContent = yield* params.generateText(providerOptions)
+      const rawContent = yield* generateWithNonIncrementalFallback()
       const content = yield* Schema.decodeEffect(ResponseSchema)(rawContent)
+      if (tracker) {
+        const responseMetadata = content.find((part) => part.type === "response-metadata")
+        if (Predicate.isNotUndefined(responseMetadata) && Predicate.isNotUndefined(responseMetadata.id)) {
+          tracker.markParts(providerOptions.prompt.content, responseMetadata.id)
+        }
+      }
       return content as Array<Response.Part<Tools>>
     }
 
-    // Pre-resolve tool approvals before calling the LLM
+    // Pre-resolve pending tool approvals before calling the LLM
     if (hasPendingApprovals) {
-      // Validate all approved tools exist in the toolkit
       for (const approval of approved) {
         if (approval.toolCall && !toolkit.tools[approval.toolCall.name]) {
           return yield* AiError.make({
@@ -965,7 +1050,6 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
         }
       }
 
-      // Execute approved tools and create denial results
       const approvedResults = yield* executeApprovedToolCalls(
         approved,
         toolkit,
@@ -974,24 +1058,43 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
       const deniedResults = createDenialResults(denied)
       const preResolvedResults = [...approvedResults, ...deniedResults]
 
-      // Add pre-resolved results to the prompt
       if (preResolvedResults.length > 0) {
-        const toolMessage = Prompt.makeMessage("tool", {
-          content: preResolvedResults
-        })
         providerOptions.prompt = Prompt.fromMessages([
           ...providerOptions.prompt.content,
-          toolMessage
+          Prompt.makeMessage("tool", { content: preResolvedResults })
         ])
       }
     }
 
+    // Strip all resolved approval artifacts (both current and from previous
+    // rounds) in a single pass before sending to the provider.
+    {
+      const { approved: allResolved, denied: allDenied } = collectToolApprovals(
+        providerOptions.prompt.content
+      )
+      if (allResolved.length > 0 || allDenied.length > 0) {
+        providerOptions.prompt = stripResolvedApprovals(
+          providerOptions.prompt,
+          allResolved,
+          allDenied
+        )
+      }
+    }
+
     const tools = typeof toolChoice === "object" && "oneOf" in toolChoice
       ? Object.values(toolkit.tools).filter((tool) => toolChoice.oneOf.includes(tool.name))
       : Object.values(toolkit.tools)
     providerOptions.tools = tools
     providerOptions.toolChoice = toolChoice
 
+    if (tracker) {
+      const prepared = tracker.prepareUnsafe(providerOptions.prompt)
+      if (Option.isSome(prepared)) {
+        providerOptions.previousResponseId = prepared.value.previousResponseId
+        providerOptions.incrementalPrompt = prepared.value.prompt
+      }
+    }
+
     // Construct the response schema with the tools from the toolkit
     const ResponseSchema = Schema.mutable(
       Schema.Array(Response.Part(toolkit))
@@ -1000,12 +1103,18 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
     // If tool call resolution is disabled, return the response without
     // resolving the tool calls that were generated
     if (options.disableToolCallResolution === true) {
-      const rawContent = yield* params.generateText(providerOptions)
+      const rawContent = yield* generateWithNonIncrementalFallback()
       const content = yield* Schema.decodeEffect(ResponseSchema)(rawContent)
+      if (tracker) {
+        const responseMetadata = content.find((part) => part.type === "response-metadata")
+        if (Predicate.isNotUndefined(responseMetadata) && Predicate.isNotUndefined(responseMetadata.id)) {
+          tracker.markParts(providerOptions.prompt.content, responseMetadata.id)
+        }
+      }
       return content as Array<Response.Part<Tools>>
     }
 
-    const rawContent = yield* params.generateText(providerOptions)
+    const rawContent = yield* generateWithNonIncrementalFallback()
 
     // Resolve the generated tool calls
     const toolResults = yield* resolveToolCalls(
@@ -1024,6 +1133,13 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
 
     const content = yield* Schema.decodeEffect(ResponseSchema)(rawContent)
 
+    if (tracker) {
+      const responseMetadata = content.find((part) => part.type === "response-metadata")
+      if (Predicate.isNotUndefined(responseMetadata) && Predicate.isNotUndefined(responseMetadata.id)) {
+        tracker.markParts(providerOptions.prompt.content, responseMetadata.id)
+      }
+    }
+
     // Return the content merged with the tool call results
     return [...content, ...toolResults] as Array<Response.Part<Tools>>
   })
@@ -1040,21 +1156,11 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
       AiError.AiError | Schema.SchemaError,
       IdGenerator
     >,
-    Options extends {
-      readonly toolkit: Effect.Effect<
-        Toolkit.WithHandler<Tools>,
-        infer _E,
-        infer _R
-      >
-    } ? _E
+    Options extends { readonly toolkit: infer ToolkitValue } ?
+      ExtractToolkitResolutionError<Exclude<ToolkitValue, undefined>>
       : never,
-    Options extends {
-      readonly toolkit: Effect.Effect<
-        Toolkit.WithHandler<Tools>,
-        infer _E,
-        infer _R
-      >
-    } ? _R
+    Options extends { readonly toolkit: infer ToolkitValue } ?
+      ExtractToolkitResolutionServices<Exclude<ToolkitValue, undefined>>
       : never
   > = Effect.fnUntraced(function*<
     Tools extends Record<string, Tool.Any>,
@@ -1063,8 +1169,27 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
     options: Options & GenerateTextOptions<Tools>,
     providerOptions: Mutable<ProviderOptions>
   ) {
+    const tracker = Option.getOrUndefined(yield* Effect.serviceOption(ResponseIdTracker.ResponseIdTracker))
     const toolChoice = options.toolChoice ?? "auto"
 
+    const streamWithNonIncrementalFallback = () => {
+      const requestOptions: ProviderOptions = {
+        ...providerOptions
+      }
+      const fallbackPrompt = requestOptions.prompt
+      const fallbackOptions: ProviderOptions = {
+        ...requestOptions,
+        prompt: fallbackPrompt,
+        incrementalPrompt: undefined,
+        previousResponseId: undefined
+      }
+      return requestOptions.incrementalPrompt
+        ? params.streamText(requestOptions).pipe(
+          Stream.catchReason("AiError", "InvalidRequestError", (_) => params.streamText(fallbackOptions))
+        )
+        : params.streamText(requestOptions)
+    }
+
     // Check for pending approvals that need resolution
     const { approved: pendingApproved, denied: pendingDenied } = collectToolApprovals(providerOptions.prompt.content, {
       excludeResolved: true
@@ -1085,23 +1210,40 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
           })
         })
       }
+      if (tracker) {
+        const prepared = tracker.prepareUnsafe(providerOptions.prompt)
+        if (Option.isSome(prepared)) {
+          providerOptions.previousResponseId = prepared.value.previousResponseId
+          providerOptions.incrementalPrompt = prepared.value.prompt
+        }
+      }
       const schema = Schema.NonEmptyArray(Response.StreamPart(Toolkit.empty))
       const decodeParts = Schema.decodeEffect(schema)
-      return params
-        .streamText(providerOptions)
-        .pipe(
-          Stream.mapArrayEffect((parts) => decodeParts(parts))
-        ) as Stream.Stream<
-          Response.StreamPart<Tools>,
-          AiError.AiError | Schema.SchemaError,
-          IdGenerator
-        >
+      return pipe(
+        streamWithNonIncrementalFallback(),
+        Stream.mapArrayEffect((parts) =>
+          decodeParts(parts).pipe(
+            tracker ?
+              Effect.tap((decodedParts) => {
+                for (const part of decodedParts) {
+                  if (part.type === "response-metadata" && Predicate.isNotUndefined(part.id)) {
+                    tracker.markParts(providerOptions.prompt.content, part.id)
+                  }
+                }
+                return Effect.void
+              }) :
+              identity
+          )
+        )
+      ) as Stream.Stream<
+        Response.StreamPart<Tools>,
+        AiError.AiError | Schema.SchemaError,
+        IdGenerator
+      >
     }
 
     // If there is a toolkit resolve and apply it to the provider options
-    const toolkit = "asEffect" in options.toolkit
-      ? yield* options.toolkit
-      : options.toolkit
+    const toolkit = yield* resolveToolkit<Tools, any, any>(options.toolkit)
 
     // If the toolkit is empty, return immediately
     if (Object.values(toolkit.tools).length === 0) {
@@ -1117,22 +1259,42 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
           })
         })
       }
+      if (tracker) {
+        const prepared = tracker.prepareUnsafe(providerOptions.prompt)
+        if (Option.isSome(prepared)) {
+          providerOptions.previousResponseId = prepared.value.previousResponseId
+          providerOptions.incrementalPrompt = prepared.value.prompt
+        }
+      }
       const schema = Schema.NonEmptyArray(Response.StreamPart(Toolkit.empty))
       const decodeParts = Schema.decodeEffect(schema)
-      return params
-        .streamText(providerOptions)
-        .pipe(
-          Stream.mapArrayEffect((parts) => decodeParts(parts))
-        ) as Stream.Stream<
-          Response.StreamPart<Tools>,
-          AiError.AiError | Schema.SchemaError,
-          IdGenerator
-        >
+      return pipe(
+        streamWithNonIncrementalFallback(),
+        Stream.mapArrayEffect((parts) =>
+          decodeParts(parts).pipe(
+            tracker ?
+              Effect.tap((decodedParts) => {
+                for (const part of decodedParts) {
+                  if (part.type === "response-metadata" && part.id) {
+                    tracker.markParts(providerOptions.prompt.content, part.id)
+                  }
+                }
+                return Effect.void
+              }) :
+              identity
+          )
+        )
+      ) as Stream.Stream<
+        Response.StreamPart<Tools>,
+        AiError.AiError | Schema.SchemaError,
+        IdGenerator
+      >
     }
 
-    // Pre-resolve tool approvals before calling the LLM
+    // Pre-resolve pending tool approvals before calling the LLM
+    let preResolvedStreamParts: Array<Response.StreamPart<Tools>> = []
+
     if (hasPendingApprovals) {
-      // Validate all approved tools exist in the toolkit
       for (const approval of pendingApproved) {
         if (approval.toolCall && !toolkit.tools[approval.toolCall.name]) {
           return yield* AiError.make({
@@ -1146,7 +1308,6 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
         }
       }
 
-      // Execute approved tools and create denial results
       const approvedResults = yield* executeApprovedToolCalls(
         pendingApproved,
         toolkit,
@@ -1155,16 +1316,44 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
       const deniedResults = createDenialResults(pendingDenied)
       const preResolvedResults = [...approvedResults, ...deniedResults]
 
-      // Add pre-resolved results to the prompt
       if (preResolvedResults.length > 0) {
-        const toolMessage = Prompt.makeMessage("tool", {
-          content: preResolvedResults
-        })
         providerOptions.prompt = Prompt.fromMessages([
           ...providerOptions.prompt.content,
-          toolMessage
+          Prompt.makeMessage("tool", { content: preResolvedResults })
         ])
       }
+
+      // Emit pre-resolved tool-results as stream parts so Chat.streamText
+      // persists them to history. This lets collectToolApprovals find them
+      // on subsequent rounds and skip the now-resolved approvals.
+      // Note: r.result is already encoded (from executeApprovedToolCalls /
+      // createDenialResults), so it goes into both result and encodedResult.
+      for (const r of preResolvedResults) {
+        preResolvedStreamParts.push(
+          Response.makePart("tool-result", {
+            id: r.id,
+            name: r.name,
+            providerExecuted: false,
+            preliminary: false,
+            result: r.result,
+            encodedResult: r.result,
+            isFailure: r.isFailure
+          }) as Response.StreamPart<Tools>
+        )
+      }
+    }
+
+    // Strip all resolved approval artifacts (both current and from previous
+    // rounds) in a single pass before sending to the provider.
+    const { approved: allResolved, denied: allDenied } = collectToolApprovals(
+      providerOptions.prompt.content
+    )
+    if (allResolved.length > 0 || allDenied.length > 0) {
+      providerOptions.prompt = stripResolvedApprovals(
+        providerOptions.prompt,
+        allResolved,
+        allDenied
+      )
     }
 
     const tools = typeof toolChoice === "object" && "oneOf" in toolChoice
@@ -1173,20 +1362,39 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
     providerOptions.tools = tools
     providerOptions.toolChoice = toolChoice
 
+    if (tracker) {
+      const prepared = tracker.prepareUnsafe(providerOptions.prompt)
+      if (Option.isSome(prepared)) {
+        providerOptions.previousResponseId = prepared.value.previousResponseId
+        providerOptions.incrementalPrompt = prepared.value.prompt
+      }
+    }
+
     // If tool call resolution is disabled, return the response without
     // resolving the tool calls that were generated
     if (options.disableToolCallResolution === true) {
       const schema = Schema.NonEmptyArray(Response.StreamPart(toolkit))
       const decodeParts = Schema.decodeEffect(schema)
-      return params
-        .streamText(providerOptions)
-        .pipe(
-          Stream.mapArrayEffect((parts) => decodeParts(parts))
-        ) as Stream.Stream<
-          Response.StreamPart<Tools>,
-          AiError.AiError | Schema.SchemaError,
-          IdGenerator
-        >
+      return streamWithNonIncrementalFallback().pipe(
+        Stream.mapArrayEffect((parts) =>
+          decodeParts(parts).pipe(
+            tracker ?
+              Effect.tap((decodedParts) => {
+                for (const part of decodedParts) {
+                  if (part.type === "response-metadata" && Predicate.isNotUndefined(part.id)) {
+                    tracker.markParts(providerOptions.prompt.content, part.id)
+                  }
+                }
+                return Effect.void
+              }) :
+              identity
+          )
+        )
+      ) as Stream.Stream<
+        Response.StreamPart<Tools>,
+        AiError.AiError | Schema.SchemaError,
+        IdGenerator
+      >
     }
 
     const ResponseSchema = Schema.NonEmptyArray(Response.StreamPart(toolkit))
@@ -1196,59 +1404,81 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
     const queue = yield* Queue.make<
       Response.StreamPart<Tools>,
       | AiError.AiError
-      | AiError.AiErrorReason
       | Cause.Done
       | Schema.SchemaError
     >()
+    const deferredFinishParts: Array<Response.StreamPart<Tools>> = []
+
+    // Emit pre-resolved tool results so Chat.streamText persists them to
+    // history. This ensures collectToolApprovals({ excludeResolved }) can
+    // find the corresponding tool-results on future rounds.
+    if (preResolvedStreamParts.length > 0) {
+      yield* Queue.offerAll(queue, preResolvedStreamParts)
+    }
 
     // FiberSet to track concurrent tool call handlers
     const toolCallFibers = yield* FiberSet.make<void, AiError.AiError>()
 
     // Helper function to handle tool calls with approval logic
-    const handleToolCall = (part: Response.ToolCallPartEncoded) =>
-      Effect.gen(function*() {
-        const tool = toolkit.tools[part.name]
-        if (!tool) {
-          return
-        }
+    const handleToolCall = Effect.fnUntraced(function*(part: Response.ToolCallPartEncoded) {
+      const tool = toolkit.tools[part.name]
+      if (!tool) return
+
+      const needsApproval = yield* isApprovalNeeded(
+        tool,
+        part,
+        providerOptions.prompt.content
+      )
 
-        const needsApproval = yield* isApprovalNeeded(
-          tool,
-          part,
-          providerOptions.prompt.content
-        )
+      if (needsApproval) {
+        const idGen = yield* IdGenerator
+        const approvalId = yield* idGen.generateId()
+        const approvalPart = Response.makePart("tool-approval-request", {
+          approvalId,
+          toolCallId: part.id
+        }) as Response.StreamPart<Tools>
+        yield* Queue.offer(queue, approvalPart)
+        return
+      }
 
-        if (needsApproval) {
-          const idGen = yield* IdGenerator
-          const approvalId = yield* idGen.generateId()
-          const approvalPart = Response.makePart("tool-approval-request", {
-            approvalId,
-            toolCallId: part.id
+      yield* toolkit.handle(part.name, part.params as any).pipe(
+        Stream.unwrap,
+        Stream.runForEach((result) => {
+          const toolResultPart = Response.makePart("tool-result", {
+            id: part.id,
+            name: part.name,
+            providerExecuted: false,
+            ...result
           }) as Response.StreamPart<Tools>
-          yield* Queue.offer(queue, approvalPart)
-          return
-        }
-
-        yield* toolkit.handle(part.name, part.params as any).pipe(
-          Stream.unwrap,
-          Stream.runForEach((result) => {
-            const toolResultPart = Response.makePart("tool-result", {
-              id: part.id,
-              name: part.name,
-              providerExecuted: false,
-              ...result
-            }) as Response.StreamPart<Tools>
-            return Queue.offer(queue, toolResultPart)
-          })
-        )
-      })
+          return Queue.offer(queue, toolResultPart)
+        })
+      )
+    })
 
-    yield* params.streamText(providerOptions).pipe(
+    yield* streamWithNonIncrementalFallback().pipe(
       Stream.runForEachArray(
         Effect.fnUntraced(function*(chunk) {
           const parts = yield* decodeParts(chunk)
-          // Add decoded response parts to the output queue
-          yield* Queue.offerAll(queue, parts)
+          if (tracker) {
+            for (const part of parts) {
+              if (part.type === "response-metadata" && part.id) {
+                tracker.markParts(providerOptions.prompt.content, part.id)
+              }
+            }
+          }
+          // Defer finish parts until all tool handlers complete. This guarantees
+          // tool results are emitted before finish in streaming mode.
+          const immediateParts: Array<Response.StreamPart<Tools>> = []
+          for (const part of parts) {
+            if (part.type === "finish") {
+              deferredFinishParts.push(part)
+            } else {
+              immediateParts.push(part)
+            }
+          }
+          if (immediateParts.length > 0) {
+            yield* Queue.offerAll(queue, immediateParts)
+          }
           // Fork tool call handlers - use the raw chunk for encoded params
           for (const part of chunk) {
             if (part.type === "tool-call" && part.providerExecuted !== true) {
@@ -1266,6 +1496,9 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
           FiberSet.awaitEmpty(toolCallFibers)
         )
       ),
+      Effect.andThen(
+        Queue.offerAll(queue, deferredFinishParts)
+      ),
       // And then end the queue
       Effect.andThen(Queue.end(queue)),
       Effect.tapCause((cause) => Queue.failCause(queue, cause)),
@@ -1310,20 +1543,27 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
  * @since 4.0.0
  * @category text generation
  */
-export const generateText = <
-  Options extends NoExcessProperties<GenerateTextOptions<any>, Options>,
-  Tools extends Record<string, Tool.Any> = {}
+export function generateText<
+  Options extends NoExcessProperties<GenerateTextOptions<any>, Options>
 >(
-  options: Options & GenerateTextOptions<Tools>
+  options: Options & GenerateTextOptions<ExtractTools<Options>>
 ): Effect.Effect<
-  GenerateTextResponse<Tools>,
+  GenerateTextResponse<ExtractTools<Options>>,
   ExtractError<Options>,
   LanguageModel | ExtractServices<Options>
-> =>
-  Effect.flatMap(
+>
+export function generateText(
+  options: GenerateTextOptions<any>
+): Effect.Effect<
+  GenerateTextResponse<any>,
+  AiError.AiError,
+  LanguageModel
+> {
+  return Effect.flatMap(
     Effect.service(LanguageModel),
-    (model) => model.generateText(options)
+    (model) => model.generateText(options as any)
   )
+}
 
 /**
  * Generate a structured object from a schema using a language model.
@@ -1357,25 +1597,32 @@ export const generateText = <
  * @since 4.0.0
  * @category object generation
  */
-export const generateObject = <
+export function generateObject<
   ObjectEncoded extends Record<string, any>,
-  StructuredOutputSchema extends Schema.Codec<any, ObjectEncoded, any, any>,
+  StructuredOutputSchema extends Schema.Encoder<ObjectEncoded, unknown>,
   Options extends NoExcessProperties<
     GenerateObjectOptions<any, StructuredOutputSchema>,
     Options
-  >,
-  Tools extends Record<string, Tool.Any> = {}
+  >
 >(
-  options: Options & GenerateObjectOptions<Tools, StructuredOutputSchema>
+  options: Options & GenerateObjectOptions<ExtractTools<Options>, StructuredOutputSchema>
 ): Effect.Effect<
-  GenerateObjectResponse<Tools, StructuredOutputSchema["Type"]>,
+  GenerateObjectResponse<ExtractTools<Options>, StructuredOutputSchema["Type"]>,
   ExtractError<Options>,
   ExtractServices<Options> | StructuredOutputSchema["DecodingServices"] | LanguageModel
-> =>
-  Effect.flatMap(
+>
+export function generateObject(
+  options: GenerateObjectOptions<any, Schema.Top>
+): Effect.Effect<
+  GenerateObjectResponse<any, any>,
+  AiError.AiError,
+  LanguageModel
+> {
+  return Effect.flatMap(
     Effect.service(LanguageModel),
-    (model) => model.generateObject(options)
-  )
+    (model) => model.generateObject(options as any)
+  ) as any
+}
 
 /**
  * Generate text using a language model with streaming output.
@@ -1401,20 +1648,27 @@ export const generateObject = <
  * @since 4.0.0
  * @category text generation
  */
-export const streamText = <
-  Options extends NoExcessProperties<GenerateTextOptions<any>, Options>,
-  Tools extends Record<string, Tool.Any> = {}
+export function streamText<
+  Options extends NoExcessProperties<GenerateTextOptions<any>, Options>
 >(
-  options: Options & GenerateTextOptions<Tools>
+  options: Options & GenerateTextOptions<ExtractTools<Options>>
 ): Stream.Stream<
-  Response.StreamPart<Tools>,
+  Response.StreamPart<ExtractTools<Options>>,
   ExtractError<Options>,
   ExtractServices<Options> | LanguageModel
-> =>
-  Stream.unwrap(Effect.map(
+>
+export function streamText(
+  options: GenerateTextOptions<any>
+): Stream.Stream<
+  Response.StreamPart<any>,
+  AiError.AiError,
+  LanguageModel
+> {
+  return Stream.unwrap(Effect.map(
     Effect.service(LanguageModel),
-    (model) => model.streamText(options)
-  ))
+    (model) => model.streamText(options as any)
+  )) as any
+}
 
 // =============================================================================
 // Tool Approval Helpers
@@ -1506,6 +1760,63 @@ const collectToolApprovals = (
   return { approved, denied }
 }
 
+/**
+ * Strip resolved approval artifacts from the prompt before sending to the
+ * provider. After pre-resolving approvals (executing approved tools and
+ * creating denial results), the original `tool-approval-request` parts in
+ * assistant messages and `tool-approval-response` parts in tool messages are
+ * no longer needed. Leaving them in causes provider-specific errors (e.g.
+ * OpenAI rejects `mcp_approval_response` items that reference approval
+ * requests it never issued).
+ */
+const stripResolvedApprovals = (
+  prompt: Prompt.Prompt,
+  approved: ReadonlyArray<ApprovalResult>,
+  denied: ReadonlyArray<ApprovalResult>
+): Prompt.Prompt => {
+  const resolvedApprovalIds = new Set<string>()
+  for (const a of approved) resolvedApprovalIds.add(a.approvalId)
+  for (const d of denied) resolvedApprovalIds.add(d.approvalId)
+
+  const cleanedMessages: Array<Prompt.Message> = []
+
+  for (const message of prompt.content) {
+    if (message.role === "assistant") {
+      const filteredContent = message.content.filter(
+        (part) =>
+          part.type !== "tool-approval-request" ||
+          !resolvedApprovalIds.has(part.approvalId)
+      )
+      if (filteredContent.length > 0) {
+        cleanedMessages.push(
+          Prompt.makeMessage("assistant", {
+            content: filteredContent,
+            options: message.options
+          })
+        )
+      }
+    } else if (message.role === "tool") {
+      const filteredContent = message.content.filter(
+        (part) =>
+          part.type !== "tool-approval-response" ||
+          !resolvedApprovalIds.has(part.approvalId)
+      )
+      if (filteredContent.length > 0) {
+        cleanedMessages.push(
+          Prompt.makeMessage("tool", {
+            content: filteredContent,
+            options: message.options
+          })
+        )
+      }
+    } else {
+      cleanedMessages.push(message)
+    }
+  }
+
+  return Prompt.fromMessages(cleanedMessages)
+}
+
 const isApprovalNeeded = Effect.fnUntraced(function*<T extends Tool.Any>(
   tool: T,
   toolCall: Response.ToolCallPartEncoded,
@@ -1734,11 +2045,11 @@ const resolveToolCalls = <Tools extends Record<string, Tool.Any>>(
 // =============================================================================
 
 const resolveToolkit = <Tools extends Record<string, Tool.Any>, E, R>(
-  toolkit:
-    | Toolkit.WithHandler<Tools>
-    | Effect.Yieldable<Toolkit.Toolkit<any>, Toolkit.WithHandler<Tools>, E, R>
+  toolkit: ToolkitOption<Tools, E, R>
 ): Effect.Effect<Toolkit.WithHandler<Tools>, E, R> =>
-  "asEffect" in toolkit ? toolkit.asEffect() : Effect.succeed(toolkit)
+  ("asEffect" in toolkit
+    ? toolkit.asEffect()
+    : Effect.succeed(toolkit as unknown as Toolkit.WithHandler<Tools>)) as any
 
 /** @internal */
 export const getObjectName = <StructuredOutputSchema extends Schema.Top>(
@@ -1761,29 +2072,32 @@ export const getObjectName = <StructuredOutputSchema extends Schema.Top>(
 const resolveStructuredOutput = Effect.fnUntraced(function*<
   StructuredOutputSchema extends Schema.Top
 >(response: ReadonlyArray<Response.AllParts<any>>, schema: StructuredOutputSchema) {
-  const text: Array<string> = []
+  const texts: Array<string> = []
   for (const part of response) {
     if (part.type === "text") {
-      text.push(part.text)
+      texts.push(part.text)
     }
   }
 
+  const text = texts.join("")
+
   if (text.length === 0) {
     return yield* AiError.make({
       module: "LanguageModel",
       method: "generateObject",
       reason: new AiError.StructuredOutputError({
-        description: "No text content in response"
+        description: "No text content in response",
+        responseText: text
       })
     })
   }
 
   const decode = Schema.decodeEffect(Schema.fromJsonString(schema))
-  return yield* Effect.mapError(decode(text.join("")), (error) =>
+  return yield* Effect.mapError(decode(text), (error) =>
     AiError.make({
       module: "LanguageModel",
       method: "generateObject",
-      reason: AiError.StructuredOutputError.fromSchemaError(error)
+      reason: AiError.StructuredOutputError.fromSchemaError(error, text)
     }))
 })