effect 4.0.0-beta.31 → 4.0.0-beta.33

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"
@@ -648,6 +649,16 @@ 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
 }
 
 /**
@@ -727,7 +738,9 @@ export const make: (params: {
             tools: [],
             toolChoice: "none",
             responseFormat: { type: "text" },
-            span
+            span,
+            previousResponseId: undefined,
+            incrementalPrompt: undefined
           }
           const content = yield* generateContent(options, providerOptions)
 
@@ -790,7 +803,9 @@ export const make: (params: {
               objectName,
               schema: options.schema
             },
-            span
+            span,
+            previousResponseId: undefined,
+            incrementalPrompt: undefined
           }
 
           const content = yield* generateContent(options, providerOptions)
@@ -857,7 +872,9 @@ export const make: (params: {
         tools: [],
         toolChoice: "none",
         responseFormat: { type: "text" },
-        span
+        span,
+        previousResponseId: undefined,
+        incrementalPrompt: undefined
       }
 
       // Resolve the content stream for the request
@@ -917,6 +934,7 @@ export const make: (params: {
     options: Options & GenerateTextOptions<Tools>,
     providerOptions: Mutable<ProviderOptions>
   ) {
+    const tracker = Option.getOrUndefined(yield* Effect.serviceOption(ResponseIdTracker.ResponseIdTracker))
     const toolChoice = options.toolChoice ?? "auto"
 
     // Check for pending approvals that need resolution
@@ -940,11 +958,24 @@ export const make: (params: {
           })
         })
       }
+      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 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>>
     }
 
@@ -965,11 +996,24 @@ export const make: (params: {
           })
         })
       }
+      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 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>>
     }
 
@@ -1025,6 +1069,14 @@ export const make: (params: {
     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))
@@ -1035,6 +1087,12 @@ export const make: (params: {
     if (options.disableToolCallResolution === true) {
       const rawContent = yield* params.generateText(providerOptions)
       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>>
     }
 
@@ -1057,6 +1115,13 @@ export const make: (params: {
 
     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>>
   })
@@ -1086,6 +1151,7 @@ export const make: (params: {
     options: Options & GenerateTextOptions<Tools>,
     providerOptions: Mutable<ProviderOptions>
   ) {
+    const tracker = Option.getOrUndefined(yield* Effect.serviceOption(ResponseIdTracker.ResponseIdTracker))
     const toolChoice = options.toolChoice ?? "auto"
 
     // Check for pending approvals that need resolution
@@ -1108,17 +1174,36 @@ export const make: (params: {
           })
         })
       }
+      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(
+        params.streamText(providerOptions),
+        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
@@ -1138,17 +1223,36 @@ export const make: (params: {
           })
         })
       }
+      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(
+        params.streamText(providerOptions),
+        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 pending tool approvals before calling the LLM
@@ -1222,20 +1326,39 @@ export const make: (params: {
     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 params.streamText(providerOptions).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))
@@ -1260,48 +1383,52 @@ export const make: (params: {
     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
+        }) 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)
-          })
-        )
-      })
+      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)
+        })
+      )
+    })
 
     yield* params.streamText(providerOptions).pipe(
       Stream.runForEachArray(
         Effect.fnUntraced(function*(chunk) {
           const parts = yield* decodeParts(chunk)
+          if (tracker) {
+            for (const part of parts) {
+              if (part.type === "response-metadata" && part.id) {
+                tracker.markParts(providerOptions.prompt.content, part.id)
+              }
+            }
+          }
           // Add decoded response parts to the output queue
           yield* Queue.offerAll(queue, parts)
           // Fork tool call handlers - use the raw chunk for encoded params

package/src/unstable/ai/OpenAiStructuredOutput.ts

@@ -11,6 +11,7 @@ import * as Rec from "../../Record.ts"
 import * as Schema from "../../Schema.ts"
 import * as AST from "../../SchemaAST.ts"
 import * as Transformation from "../../SchemaTransformation.ts"
+import * as Tool from "./Tool.ts"
 
 /**
  * Transforms a `Schema.Codec` into a form compatible with OpenAI's
@@ -243,6 +244,9 @@ function recurOpenAI(ast: AST.AST): AST.AST {
         }
       } else if (ast.indexSignatures.length === 1 && ast.propertySignatures.length === 0) {
         const is = ast.indexSignatures[0]
+        if (Tool.isEmptyParamsRecord(is)) {
+          return ast
+        }
         // records are not supported by OpenAI, so we translate them to arrays of key-value pairs
         if (annotations !== undefined && typeof annotations.description === "string") {
           annotations.description = `${RECORD_DESCRIPTION}; ${annotations.description}`

package/src/unstable/ai/ResponseIdTracker.ts

@@ -0,0 +1,97 @@
+/**
+ * @since 4.0.0
+ */
+import * as Effect from "../../Effect.ts"
+import * as Option from "../../Option.ts"
+import * as ServiceMap from "../../ServiceMap.ts"
+import * as Prompt from "./Prompt.ts"
+
+/**
+ * @since 4.0.0
+ * @category models
+ */
+export interface PrepareResult {
+  readonly previousResponseId: string
+  readonly prompt: Prompt.Prompt
+}
+
+/**
+ * @since 4.0.0
+ * @category models
+ */
+export interface Service {
+  clearUnsafe(): void
+  markParts(parts: ReadonlyArray<object>, responseId: string): void
+  prepareUnsafe(prompt: Prompt.Prompt): Option.Option<PrepareResult>
+}
+
+/**
+ * @since 4.0.0
+ * @category Services
+ */
+export class ResponseIdTracker
+  extends ServiceMap.Service<ResponseIdTracker, Service>()("effect/ai/ResponseIdTracker")
+{}
+
+/**
+ * @since 4.0.0
+ * @category constructors
+ */
+export const make: Effect.Effect<Service> = Effect.sync(() => {
+  let sentParts = new WeakMap<object, string>()
+
+  const none = () => {
+    sentParts = new WeakMap<object, string>()
+    return Option.none<PrepareResult>()
+  }
+
+  return {
+    clearUnsafe() {
+      sentParts = new WeakMap<object, string>()
+    },
+    markParts(parts, responseId) {
+      for (let i = 0; i < parts.length; i++) {
+        sentParts.set(parts[i], responseId)
+      }
+    },
+    prepareUnsafe(prompt) {
+      const messages = prompt.content
+
+      let anyTracked = false
+      for (let i = 0; i < messages.length; i++) {
+        if (sentParts.has(messages[i])) {
+          anyTracked = true
+          break
+        }
+      }
+      if (!anyTracked) return none()
+
+      let lastAssistantIndex = -1
+      for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === "assistant") {
+          lastAssistantIndex = i
+          break
+        }
+      }
+      if (lastAssistantIndex === -1) return none()
+
+      let responseId: string | undefined
+      for (let i = 0; i < lastAssistantIndex; i++) {
+        const id = sentParts.get(messages[i])
+        if (id === undefined) return none()
+        responseId = id
+      }
+      if (responseId === undefined) return none()
+
+      const partsAfterLastAssistant = messages.slice(lastAssistantIndex + 1)
+      if (partsAfterLastAssistant.length === 0) {
+        return none()
+      }
+
+      return Option.some({
+        previousResponseId: responseId,
+        prompt: Prompt.fromMessages(partsAfterLastAssistant)
+      })
+    }
+  }
+})

package/src/unstable/ai/Tool.ts

@@ -1129,6 +1129,9 @@ const dynamicProto = <
  * can call. The tool definition includes parameter validation, success/failure
  * schemas, and optional service dependencies.
  *
+ * If a tool accepts no parameters but still needs an explicit empty object
+ * schema, use {@link EmptyParams}.
+ *
  * @example
  * ```ts
  * import { Schema } from "effect"
@@ -1866,3 +1869,20 @@ export const unsafeSecureJsonParse = (text: string): unknown => {
     Error.stackTraceLimit = stackTraceLimit
   }
 }
+
+/**
+ * @since 4.0.0
+ */
+export interface EmptyParams extends Schema.$Record<Schema.String, Schema.Never> {}
+
+/**
+ * A schema for tools that accept no parameters.
+ *
+ * @since 4.0.0
+ */
+export const EmptyParams: EmptyParams = Schema.Record(Schema.String, Schema.Never)
+
+/** @internal */
+export function isEmptyParamsRecord(indexSignature: AST.IndexSignature): boolean {
+  return indexSignature.parameter === AST.string && AST.isNever(indexSignature.type)
+}

package/src/unstable/ai/index.ts

@@ -388,6 +388,11 @@ export * as Prompt from "./Prompt.ts"
  */
 export * as Response from "./Response.ts"
 
+/**
+ * @since 4.0.0
+ */
+export * as ResponseIdTracker from "./ResponseIdTracker.ts"
+
 /**
  * The `Telemetry` module provides OpenTelemetry integration for operations
  * performed against a large language model provider by defining telemetry

package/src/unstable/cli/Argument.ts

@@ -226,9 +226,7 @@ export const fileParse = (
  *   host: Schema.String
  * })
  *
- * const JsonConfigSchema = Schema.fromJsonString(ConfigSchema)
- *
- * const config = Argument.fileSchema("config", JsonConfigSchema)
+ * const config = Argument.fileSchema("config", ConfigSchema)
  * ```
  *
  * @since 4.0.0
@@ -236,7 +234,7 @@ export const fileParse = (
  */
 export const fileSchema = <A>(
   name: string,
-  schema: Schema.Codec<A, string>,
+  schema: Schema.Decoder<A>,
   options?: Primitive.FileSchemaOptions | undefined
 ): Argument<A> => Param.fileSchema(Param.argumentKind, name, schema, options)
 

package/src/unstable/cli/CliOutput.ts

@@ -3,6 +3,7 @@
  */
 
 import * as Layer from "../../Layer.ts"
+import * as Option from "../../Option.ts"
 import * as ServiceMap from "../../ServiceMap.ts"
 import type * as CliError from "./CliError.ts"
 import type { HelpDoc } from "./HelpDoc.ts"
@@ -44,6 +45,7 @@ export interface Formatter {
    *
    * @example
    * ```ts
+   * import { Option as O } from "effect"
    * import type { HelpDoc } from "effect/unstable/cli"
    * import { CliOutput } from "effect/unstable/cli"
    *
@@ -55,7 +57,7 @@ export interface Formatter {
    *       name: "verbose",
    *       aliases: ["-v"],
    *       type: "boolean",
-   *       description: "Enable verbose output",
+   *       description: O.some("Enable verbose output"),
    *       required: false
    *     }
    *   ],
@@ -63,7 +65,7 @@ export interface Formatter {
    *     {
    *       name: "file",
    *       type: "string",
-   *       description: "Input file to process",
+   *       description: O.some("Input file to process"),
    *       required: true,
    *       variadic: false
    *     }
@@ -459,7 +461,7 @@ const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions): string => {
       const nameType = `${coloredName} ${coloredType}`
 
       const optionalSuffix = arg.required ? "" : colors.dim(" (optional)")
-      const description = (arg.description ?? "") + optionalSuffix
+      const description = Option.getOrElse(arg.description, () => "") + optionalSuffix
 
       return {
         left: nameType,
@@ -491,7 +493,7 @@ const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions): string => {
 
       return {
         left: namesPart + typePart,
-        right: flag.description ?? ""
+        right: Option.getOrElse(flag.description, () => "")
       }
     })
 
@@ -519,7 +521,7 @@ const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions): string => {
 
       return {
         left: namesPart + typePart,
-        right: flag.description ?? ""
+        right: Option.getOrElse(flag.description, () => "")
       }
     })
 

package/src/unstable/cli/Command.ts

@@ -360,10 +360,10 @@ export interface ParsedTokens {
   readonly flags: Record<string, ReadonlyArray<string>>
   readonly arguments: ReadonlyArray<string>
   readonly errors?: ReadonlyArray<CliError.CliError>
-  readonly subcommand?: {
+  readonly subcommand: Option.Option<{
     readonly name: string
     readonly parsedInput: ParsedTokens
-  }
+  }>
 }
 
 /**
@@ -939,17 +939,17 @@ export const withSubcommands: {
   type InternalInput = NextInput & { readonly [SubcommandStateSymbol]?: SubcommandState }
 
   const parse = Effect.fnUntraced(function*(raw: ParsedTokens) {
-    if (!raw.subcommand) {
+    if (Option.isNone(raw.subcommand)) {
       return (yield* impl.parse(raw)) as NextInput
     }
 
-    const sub = byName.get(raw.subcommand.name)
+    const sub = byName.get(raw.subcommand.value.name)
     if (!sub) {
       return (yield* impl.parse(raw)) as NextInput
     }
 
     const context = yield* impl.parseContext(raw)
-    const result = yield* sub.parse(raw.subcommand.parsedInput)
+    const result = yield* sub.parse(raw.subcommand.value.parsedInput)
     return Object.assign({}, context, { [SubcommandStateSymbol]: { name: sub.name, result } }) as NextInput
   })