effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/unstable/ai/Response.ts

@@ -165,6 +165,8 @@ export type AllPartsEncoded =
 /**
  * Creates a Schema for all response parts based on a toolkit.
  *
+ * **Details**
+ *
  * Generates a schema that includes all possible response parts, with tool call
  * and tool result parts dynamically created based on the provided toolkit.
  *
@@ -459,9 +461,8 @@ export const ProviderMetadata: Schema.$Record<
 export type ProviderMetadata = typeof ProviderMetadata.Type
 
 /**
- * Base interface for all response content parts.
- *
- * Provides common structure including type identifier and optional metadata.
+ * Base interface for all response content parts, including the type identifier
+ * and optional metadata.
  *
  * @category models
  * @since 4.0.0
@@ -637,9 +638,8 @@ export const TextPart: Schema.Struct<{
 // =============================================================================
 
 /**
- * Response part indicating the start of streaming text content.
- *
- * Marks the beginning of a text chunk with a unique identifier.
+ * Response part indicating the start of streaming text content with a unique
+ * text chunk identifier.
  *
  * @category models
  * @since 4.0.0
@@ -766,9 +766,7 @@ export const TextDeltaPart: Schema.Struct<{
 // =============================================================================
 
 /**
- * Response part indicating the end of streaming text content.
- *
- * Marks the completion of a text chunk.
+ * Response part indicating the completion of a streaming text chunk.
  *
  * @category models
  * @since 4.0.0
@@ -897,9 +895,8 @@ export const ReasoningPart: Schema.Struct<{
 // =============================================================================
 
 /**
- * Response part indicating the start of streaming reasoning content.
- *
- * Marks the beginning of a reasoning chunk with a unique identifier.
+ * Response part indicating the start of streaming reasoning content with a
+ * unique reasoning chunk identifier.
  *
  * @category models
  * @since 4.0.0
@@ -1026,9 +1023,7 @@ export const ReasoningDeltaPart: Schema.Struct<{
 // =============================================================================
 
 /**
- * Response part indicating the end of streaming reasoning content.
- *
- * Marks the completion of a chunk of reasoning content.
+ * Response part indicating the completion of a streaming reasoning chunk.
  *
  * @category models
  * @since 4.0.0
@@ -1088,6 +1083,8 @@ export const ReasoningEndPart: Schema.Struct<{
 /**
  * Response part indicating the start of streaming tool parameters.
  *
+ * **Details**
+ *
  * Marks the beginning of tool parameter streaming with metadata about the tool
  * call.
  *
@@ -1174,6 +1171,8 @@ export const ToolParamsStartPart: Schema.Struct<{
 /**
  * Response part containing incremental tool parameter content.
  *
+ * **Details**
+ *
  * Represents a chunk of tool parameters being streamed, containing the
  * incremental JSON content that forms the tool parameters.
  *
@@ -1248,6 +1247,8 @@ export const ToolParamsDeltaPart: Schema.Struct<{
 /**
  * Response part indicating the end of streaming tool parameters.
  *
+ * **Details**
+ *
  * Marks the completion of a tool parameter stream, indicating that all
  * parameter data has been sent and the tool call is ready to be executed.
  *
@@ -1467,10 +1468,14 @@ export interface BaseToolResult<Name extends string> extends BasePart<"tool-resu
   /**
    * Whether this is a preliminary (intermediate) result.
    *
+   * **Details**
+   *
    * Preliminary results represent progress updates during streaming tool
    * execution. Only the final result (where `preliminary` is `false` or
    * `undefined`) should be used as the authoritative output.
    *
+   * **Gotchas**
+   *
    * Only applicable for framework-executed tools during streaming.
    */
   readonly preliminary: boolean
@@ -1585,6 +1590,8 @@ export interface ToolResultPartEncoded extends BasePartEncoded<"tool-result", To
   /**
    * Whether this is a preliminary (intermediate) result.
    *
+   * **Gotchas**
+   *
    * Only applicable for framework-executed tools during streaming.
    */
   readonly preliminary?: boolean | undefined
@@ -1721,6 +1728,8 @@ export const toolResultPart = <const Params extends ConstructorParams<ToolResult
 /**
  * Response part representing a tool approval request.
  *
+ * **Details**
+ *
  * Emitted when a tool requires user approval before execution. The framework
  * checks the tool's `needsApproval` property and emits this part instead of
  * executing the tool when approval is required.
@@ -1822,6 +1831,8 @@ export const toolApprovalRequestPart = (
 /**
  * Response part representing a file attachment.
  *
+ * **Details**
+ *
  * Supports various file types including images, documents, and binary data.
  *
  * **Example** (Creating a file part)
@@ -1901,9 +1912,8 @@ export const FilePart: Schema.Struct<{
 // =============================================================================
 
 /**
- * Response part representing a document source reference.
- *
- * Used to reference documents that were used in generating the response.
+ * Response part representing a document source reference used in generating the
+ * response.
  *
  * @category models
  * @since 4.0.0
@@ -2001,9 +2011,8 @@ export const DocumentSourcePart: Schema.Struct<{
 // =============================================================================
 
 /**
- * Response part representing a URL source reference.
- *
- * Used to reference web URLs that were used in generating the response.
+ * Response part representing a URL source reference used in generating the
+ * response.
  *
  * @category models
  * @since 4.0.0
@@ -2093,6 +2102,8 @@ export const UrlSourcePart: Schema.Struct<{
 /**
  * Schema for HTTP request details associated with an AI response.
  *
+ * **Details**
+ *
  * Captures comprehensive information about the HTTP request made to the
  * AI provider, enabling inspection of request metadata for debugging and
  * observability purposes.
@@ -2131,6 +2142,8 @@ export const HttpRequestDetails = Schema.Struct({
 /**
  * Schema for HTTP response details associated with an AI response.
  *
+ * **Details**
+ *
  * Captures essential information about the HTTP response received from
  * the AI provider, including status codes and headers for debugging and
  * observability purposes.
@@ -2280,6 +2293,8 @@ export const ResponseMetadataPart: Schema.Struct<{
 /**
  * Represents the reason why a model finished generation of a response.
  *
+ * **Details**
+ *
  * Possible finish reasons:
  * - `"stop"`: The model generated a stop sequence.
  * - `"length"`: The model exceeded its token budget.
@@ -2316,6 +2331,8 @@ export const FinishReason: Schema.Literals<[
 /**
  * Type of the reason why a model stopped generating a response.
  *
+ * **Details**
+ *
  * Values include normal stops, token-limit stops, content filtering,
  * tool-call pauses, provider errors, and unknown provider-specific finish
  * reasons.
@@ -2328,6 +2345,8 @@ export type FinishReason = typeof FinishReason.Type
 /**
  * Represents usage information for a request to a large language model provider.
  *
+ * **Details**
+ *
  * If the model provider returns additional usage information than what is
  * specified here, you can generally find that information under the provider
  * metadata of the finish part of the response.

package/src/unstable/ai/ResponseIdTracker.ts

@@ -21,6 +21,8 @@ import * as Prompt from "./Prompt.ts"
 /**
  * Result returned when a tracked prompt can be sent incrementally.
  *
+ * **Details**
+ *
  * It contains the provider response ID to pass as `previousResponseId` and the
  * prompt fragment containing only the new messages after the latest assistant
  * turn.
@@ -37,6 +39,8 @@ export interface PrepareResult {
  * Mutable service that tracks prompt message object identities by provider
  * response ID.
  *
+ * **Details**
+ *
  * `markParts` records the prompt messages that produced a response,
  * `prepareUnsafe` returns a `previousResponseId` plus the untracked suffix when
  * the prompt prefix is fully recognized, and `clearUnsafe` drops all tracked
@@ -55,6 +59,8 @@ export interface Service {
  * Service tag for enabling provider previous-response ID reuse across language
  * model calls.
  *
+ * **When to use**
+ *
  * When provided, language model operations can use the tracker to send only new
  * prompt messages together with the provider's prior response ID.
  *
@@ -66,6 +72,8 @@ export class ResponseIdTracker extends Context.Service<ResponseIdTracker, Servic
 /**
  * Creates an in-memory `ResponseIdTracker` service.
  *
+ * **Details**
+ *
  * The tracker maps prompt message object identities to provider response IDs.
  * `prepareUnsafe` returns a previous response ID and the messages after the
  * latest assistant turn only when the existing prompt prefix is fully tracked;

package/src/unstable/ai/Telemetry.ts

@@ -45,8 +45,7 @@ import type * as Response from "./Response.ts"
  * The attributes used to describe telemetry in the context of Generative
  * Artificial Intelligence (GenAI) models requests and responses.
  *
- * {@see https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/}
- *
+ * @see https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/
  * @category models
  * @since 4.0.0
  */
@@ -201,6 +200,8 @@ export interface ResponseAttributes {
  * The `gen_ai.operation.name` attribute has the following list of well-known
  * values.
  *
+ * **Details**
+ *
  * If one of them applies, then the respective value **MUST** be used;
  * otherwise, a custom value **MAY** be used.
  *
@@ -212,6 +213,8 @@ export type WellKnownOperationName = "chat" | "embeddings" | "text_completion"
 /**
  * The `gen_ai.system` attribute has the following list of well-known values.
  *
+ * **Details**
+ *
  * If one of them applies, then the respective value **MUST** be used;
  * otherwise, a custom value **MAY** be used.
  *
@@ -237,6 +240,8 @@ export type WellKnownSystem =
 /**
  * Utility type for prefixing attribute names with a namespace.
  *
+ * **Details**
+ *
  * Transforms attribute keys by adding a prefix and formatting them according to
  * OpenTelemetry conventions (camelCase to snake_case).
  *
@@ -270,6 +275,8 @@ export type AttributesWithPrefix<Attributes extends Record<string, any>, Prefix
 /**
  * Utility type for converting camelCase names to snake_case format.
  *
+ * **Details**
+ *
  * This type recursively transforms string literal types from camelCase to
  * snake_case, which is the standard format for OpenTelemetry attributes.
  *
@@ -296,6 +303,8 @@ export type FormatAttributeName<T extends string | number | symbol> = T extends
  * Creates a reusable span-attribute writer for a key prefix and key
  * transformer.
  *
+ * **Details**
+ *
  * The returned function mutates the supplied span by adding each non-nullish
  * attribute as `${prefix}.${transformedKey}`.
  *
@@ -360,6 +369,8 @@ const addSpanUsageAttributes = addSpanAttributes("gen_ai.usage", String.camelToS
 /**
  * Configuration options for GenAI telemetry attributes.
  *
+ * **Details**
+ *
  * Combines base attributes with optional grouped attributes for comprehensive
  * telemetry coverage of AI operations.
  *
@@ -419,10 +430,14 @@ export type GenAITelemetryAttributeOptions = BaseAttributes & {
 /**
  * Applies GenAI telemetry attributes to an OpenTelemetry span.
  *
+ * **Details**
+ *
  * This function adds standardized GenAI attributes to a span following OpenTelemetry
  * semantic conventions. It supports both curried and direct application patterns.
  *
- * **Note**: This function mutates the provided span in-place.
+ * **Gotchas**
+ *
+ * This function mutates the provided span in-place.
  *
  * **Example** (Adding GenAI telemetry annotations)
  *
@@ -448,10 +463,14 @@ export const addGenAIAnnotations: {
   /**
    * Applies GenAI telemetry attributes to an OpenTelemetry span.
    *
+   * **Details**
+   *
    * This function adds standardized GenAI attributes to a span following OpenTelemetry
    * semantic conventions. It supports both curried and direct application patterns.
    *
-   * **Note**: This function mutates the provided span in-place.
+   * **Gotchas**
+   *
+   * This function mutates the provided span in-place.
    *
    * **Example** (Adding GenAI telemetry annotations)
    *
@@ -477,10 +496,14 @@ export const addGenAIAnnotations: {
   /**
    * Applies GenAI telemetry attributes to an OpenTelemetry span.
    *
+   * **Details**
+   *
    * This function adds standardized GenAI attributes to a span following OpenTelemetry
    * semantic conventions. It supports both curried and direct application patterns.
    *
-   * **Note**: This function mutates the provided span in-place.
+   * **Gotchas**
+   *
+   * This function mutates the provided span in-place.
    *
    * **Example** (Adding GenAI telemetry annotations)
    *
@@ -515,6 +538,8 @@ export const addGenAIAnnotations: {
 /**
  * A function that can transform OpenTelemetry spans based on AI operation data.
  *
+ * **Details**
+ *
  * Span transformers receive the complete request/response context from AI operations
  * and can add custom telemetry attributes, metrics, or other observability data.
  *

package/src/unstable/ai/Tokenizer.ts

@@ -46,6 +46,8 @@ import * as Prompt from "./Prompt.ts"
 /**
  * The `Tokenizer` service tag for dependency injection.
  *
+ * **Details**
+ *
  * This tag provides access to tokenization functionality throughout your
  * application, enabling token counting and prompt truncation capabilities.
  *
@@ -73,6 +75,8 @@ export class Tokenizer extends Context.Service<Tokenizer, Service>()(
  * Tokenizer service interface providing text tokenization and truncation
  * operations.
  *
+ * **Details**
+ *
  * This interface defines the core operations for converting text to tokens and
  * managing content length within token limits for AI model compatibility.
  *
@@ -122,6 +126,8 @@ export interface Service {
 /**
  * Creates a Tokenizer service implementation from tokenization options.
  *
+ * **Details**
+ *
  * This function constructs a complete Tokenizer service by providing a
  * tokenization function. The service handles both tokenization and
  * truncation operations using the provided tokenizer.

package/src/unstable/ai/Tool.ts

@@ -48,6 +48,8 @@ import type * as Prompt from "./Prompt.ts"
 /**
  * Runtime type identifier carried by Effect AI tool values.
  *
+ * **Details**
+ *
  * The tool type guards use this marker, together with more specific markers,
  * to distinguish user-defined, provider-defined, and dynamic tools.
  *
@@ -67,6 +69,8 @@ export type TypeId = "~effect/ai/Tool"
 /**
  * Runtime type identifier carried by provider-defined tools.
  *
+ * **Details**
+ *
  * `isProviderDefined` uses this marker to distinguish tools that are built into
  * an AI provider from user-defined and dynamic tools.
  *
@@ -87,6 +91,8 @@ export type ProviderDefinedTypeId = "~effect/ai/Tool/ProviderDefined"
 /**
  * Runtime type identifier carried by dynamic tools.
  *
+ * **Details**
+ *
  * `isDynamic` uses this marker to distinguish tools whose schema may be
  * provided at runtime from user-defined and provider-defined tools.
  *
@@ -111,6 +117,8 @@ export type DynamicTypeId = "~effect/ai/Tool/Dynamic"
  * The strategy used for handling errors returned from tool call handler
  * execution.
  *
+ * **Details**
+ *
  * If set to `"error"` (the default), errors that occur during tool call handler
  * execution will be returned in the error channel of the calling effect.
  *
@@ -154,6 +162,8 @@ export type NeedsApprovalFunction<Params extends Schema.Top> = (
 /**
  * Specifies whether user approval is required before executing a tool.
  *
+ * **Details**
+ *
  * Can be:
  * - `boolean`: Static approval requirement
  * - `NeedsApprovalFunction`: Dynamic approval based on parameters/context
@@ -168,6 +178,8 @@ export type NeedsApproval<Params extends Schema.Top> =
 /**
  * A user-defined tool that language models can call to perform actions.
  *
+ * **Details**
+ *
  * Tools represent actionable capabilities that large language models can invoke
  * to extend their functionality beyond text generation. Each tool has a defined
  * schema for parameters, results, and failures.
@@ -229,6 +241,8 @@ export interface Tool<
    * The strategy used for handling errors returned from tool call handler
    * execution.
    *
+   * **Details**
+   *
    * If set to `"error"` (the default), errors that occur during tool call
    * handler execution will be returned in the error channel of the calling
    * effect.
@@ -264,6 +278,8 @@ export interface Tool<
   /**
    * Specifies whether user approval is required before executing this tool.
    *
+   * **Details**
+   *
    * - If `undefined` or `false`, the tool executes immediately.
    * - If `true`, the tool always requires approval.
    * - If a function, it is called with the tool parameters and context to
@@ -276,6 +292,8 @@ export interface Tool<
    * Adds a _request-level_ dependency which must be provided before the tool
    * call handler can be executed.
    *
+   * **Details**
+   *
    * This can be useful when you want to enforce that a particular dependency
    * **MUST** be provided to each request to the large language model provider
    * instead of being provided when creating the tool call handler layer.
@@ -347,6 +365,8 @@ export interface Tool<
  * A provider-defined tool is a tool which is built into a large language model
  * provider (e.g. web search, code execution).
  *
+ * **Details**
+ *
  * These tools are executed by the large language model provider rather than
  * by your application. However, they can optionally require custom handlers
  * implemented in your application to process provider generated results.
@@ -434,6 +454,8 @@ export interface ProviderDefined<
 /**
  * A dynamic tool is a tool where the schema may not be known at compile time.
  *
+ * **Details**
+ *
  * Dynamic tools support two modes:
  * - **Effect Schema mode**: Full type safety with validation (like `Tool.make`)
  * - **JSON Schema mode**: Raw JSON Schema for the model, handler receives `unknown`
@@ -836,6 +858,8 @@ export type FailureResultEncoded<T> = T extends Tool<
  * A utility type to extract the type of the tool call result whether it
  * succeeds or fails.
  *
+ * **Details**
+ *
  * When `failureMode` is `"return"`, the result may also be an `AiError`.
  *
  * @category utility types
@@ -853,6 +877,8 @@ export type Result<T> = T extends Tool<
  * A utility type to extract the encoded type of the tool call result whether
  * it succeeds or fails.
  *
+ * **Details**
+ *
  * When `failureMode` is `"return"`, the result may also be an encoded `AiError`.
  *
  * @category utility types
@@ -958,6 +984,8 @@ export interface HandlerResult<Tool extends Any> {
 /**
  * Tagged union for incremental handler output.
  *
+ * **Details**
+ *
  * When a tool handler returns a `Stream`, each emitted value is tagged as
  * either:
  * - `Preliminary`: An intermediate result representing progress
@@ -1154,6 +1182,8 @@ const dynamicProto = <
 /**
  * Creates a user-defined tool with the specified name and configuration.
  *
+ * **Details**
+ *
  * This is the primary constructor for creating custom tools that AI models
  * can call. The tool definition includes parameter validation, success/failure
  * schemas, and optional service dependencies.
@@ -1205,6 +1235,8 @@ export const make = <
    * The strategy used for handling errors returned from tool call handler
    * execution.
    *
+   * **Details**
+   *
    * If set to `"error"` (the default), errors that occur during tool call handler
    * execution will be returned in the error channel of the calling effect.
    *
@@ -1219,6 +1251,8 @@ export const make = <
   /**
    * Specifies whether user approval is required before executing this tool.
    *
+   * **Details**
+   *
    * - If `undefined` or `false`, the tool executes immediately.
    * - If `true`, the tool always requires approval.
    * - If a function, it is called with the tool parameters and context to
@@ -1253,9 +1287,13 @@ export const make = <
  * Creates a dynamic tool that can accept either an Effect Schema or a raw
  * JSON Schema for its parameters.
  *
+ * **When to use**
+ *
  * This is useful for tools where the schema isn't known at compile time,
  * such as MCP tools discovered at runtime or tools from external configurations.
  *
+ * **Details**
+ *
  * - When `parameters` is an Effect Schema: full type safety with validation
  * - When `parameters` is a JSON Schema: handler receives `unknown`, no validation
  *
@@ -1294,9 +1332,13 @@ export const dynamic: {
    * Creates a dynamic tool that can accept either an Effect Schema or a raw
    * JSON Schema for its parameters.
    *
+   * **When to use**
+   *
    * This is useful for tools where the schema isn't known at compile time,
    * such as MCP tools discovered at runtime or tools from external configurations.
    *
+   * **Details**
+   *
    * - When `parameters` is an Effect Schema: full type safety with validation
    * - When `parameters` is a JSON Schema: handler receives `unknown`, no validation
    *
@@ -1386,6 +1428,8 @@ export const dynamic: {
  * Creates a provider-defined tool which leverages functionality built into a
  * large language model provider (e.g. web search, code execution).
  *
+ * **Details**
+ *
  * These tools are executed by the large language model provider rather than
  * by your application. However, they can optionally require custom handlers
  * implemented in your application to process provider generated results.
@@ -1515,6 +1559,8 @@ export const providerDefined = <
  * A utility which allows mapping between a provider-defined name for a tool
  * and the name given to the tool by the Effect AI SDK.
  *
+ * **Details**
+ *
  * The custom names used by the Effect AI SDK are to allow for toolkits which
  * contain tools from multiple different providers that would otherwise have
  * naming conflicts (i.e. `"web_search"`) to instead use custom names (i.e.
@@ -1554,6 +1600,8 @@ export class NameMapper<Tools extends ReadonlyArray<Any>> {
    * Returns the user-specified tool name that corresponds with the provided
    * provider-specified tool name.
    *
+   * **Details**
+   *
    * If the provider-specified tool name was not registered with the name mapper,
    * then the provider-specified tool name is returned.
    */
@@ -1565,6 +1613,8 @@ export class NameMapper<Tools extends ReadonlyArray<Any>> {
    * Returns the provider-specified tool name that corresponds with the provided
    * user-specified tool name.
    *
+   * **Details**
+   *
    * If the user-specified tool name was not registered with the name mapper,
    * then the user-specified tool name is returned.
    */
@@ -1576,6 +1626,8 @@ export class NameMapper<Tools extends ReadonlyArray<Any>> {
 /**
  * Extracts the description from a tool's metadata.
  *
+ * **Details**
+ *
  * Returns the tool's description if explicitly set, otherwise attempts to
  * extract it from the parameter schema's AST annotations.
  *
@@ -1608,6 +1660,8 @@ export const getDescription = <Tool extends Any>(tool: Tool): string | undefined
 /**
  * Generates a JSON Schema for a tool.
  *
+ * **Details**
+ *
  * This function creates a JSON Schema representation that can be used by
  * large language models to indicate the structure and type of the parameters
  * that a given tool call should receive.
@@ -1656,6 +1710,8 @@ export const getJsonSchema = <Tool extends Any>(tool: Tool, options?: {
 /**
  * Generates a JSON Schema from an Effect `Schema`.
  *
+ * **Details**
+ *
  * If a `CodecTransformer` is supplied, the transformed schema's JSON Schema is
  * returned. Otherwise, the schema is converted with
  * `Schema.toJsonSchemaDocument` and any generated definitions are attached as
@@ -1718,6 +1774,8 @@ export class Meta extends Context.Service<Meta, Record<string, unknown>>()("effe
 /**
  * Annotation indicating whether a tool only reads data without making changes.
  *
+ * **Details**
+ *
  * This is emitted as the MCP `readOnlyHint`; unannotated tools default to
  * `false`.
  *
@@ -1740,6 +1798,8 @@ export const Readonly = Context.Reference<boolean>("effect/ai/Tool/Readonly", {
 /**
  * Annotation indicating whether a tool may perform destructive operations.
  *
+ * **Details**
+ *
  * This is emitted as the MCP `destructiveHint`; unannotated tools default to
  * `true`, so annotate safe tools with `false`.
  *
@@ -1763,6 +1823,8 @@ export const Destructive = Context.Reference<boolean>("effect/ai/Tool/Destructiv
  * Annotation indicating whether a tool can be called repeatedly with the same
  * parameters without changing the result beyond the first call.
  *
+ * **Details**
+ *
  * This is emitted as the MCP `idempotentHint`; unannotated tools default to
  * `false`.
  *
@@ -1786,6 +1848,8 @@ export const Idempotent = Context.Reference<boolean>("effect/ai/Tool/Idempotent"
  * Annotation indicating whether a tool may interact with arbitrary external
  * data or systems.
  *
+ * **Details**
+ *
  * This is emitted as the MCP `openWorldHint`; unannotated tools default to
  * `true`.
  *
@@ -1808,6 +1872,8 @@ export const OpenWorld = Context.Reference<boolean>("effect/ai/Tool/OpenWorld",
 /**
  * Annotation controlling whether strict JSON schema mode is enabled for a tool.
  *
+ * **Details**
+ *
  * When `true`, providers that support strict mode will send `strict: true` to
  * the model API (e.g. OpenAI's Structured Outputs).
  *
@@ -1937,6 +2003,8 @@ export const unsafeSecureJsonParse = (text: string): unknown => {
 /**
  * Type of the `EmptyParams` schema used for tools with no parameters.
  *
+ * **Details**
+ *
  * It is a record schema with string keys and `never` values, so the generated
  * parameter schema accepts an empty object shape with no properties.
  *