effect 4.0.0-beta.40 → 4.0.0-beta.42

package/src/unstable/ai/LanguageModel.ts

@@ -120,16 +120,42 @@ export interface Service {
   /**
    * Generate text using the language model.
    */
-  readonly generateText: <
-    Options extends NoExcessProperties<GenerateTextOptions<any>, Options>,
-    Tools extends Record<string, Tool.Any> = {}
-  >(
-    options: Options & GenerateTextOptions<Tools>
-  ) => Effect.Effect<
-    GenerateTextResponse<Tools>,
-    ExtractError<Options>,
-    ExtractServices<Options>
-  >
+  readonly generateText: {
+    // No toolkit: force `{}` instead of falling back to `Record<string, Tool.Any>`.
+    <Options extends NoExcessProperties<GenerateTextOptionsWithoutToolkit, Options>>(
+      options: Options & GenerateTextOptionsWithoutToolkit
+    ): Effect.Effect<
+      GenerateTextResponse<{}>,
+      ExtractError<Options>,
+      ExtractServices<Options>
+    >
+    // Generic toolkit: preserve caller-supplied `Tools` in helpers like `<Tools>(toolkit: WithHandler<Tools>) => ...`.
+    <
+      Tools extends Record<string, Tool.Any>,
+      Options extends NoExcessProperties<
+        GenerateTextOptions<Tools> & { readonly toolkit: ToolkitInput<Tools> },
+        Options
+      >
+    >(
+      options: Options & GenerateTextOptions<Tools> & { readonly toolkit: ToolkitInput<Tools> }
+    ): Effect.Effect<
+      GenerateTextResponse<Tools>,
+      ExtractError<Options>,
+      ExtractServices<Options>
+    >
+    // Toolkit unions: recover distributive `ExtractTools<Options>` inference for `toolkitA | toolkitB` call sites.
+    <
+      Options extends {
+        readonly toolkit: ToolkitOption<any>
+      } & NoExcessProperties<GenerateTextOptions<any>, Options>
+    >(
+      options: Options & GenerateTextOptions<ExtractTools<Options>> & { readonly toolkit: Options["toolkit"] }
+    ): Effect.Effect<
+      GenerateTextResponse<ExtractTools<Options>>,
+      ExtractError<Options>,
+      ExtractServices<Options>
+    >
+  }
 
   /**
    * Generate a structured object from a schema using the language model.
@@ -153,16 +179,42 @@ export interface Service {
   /**
    * Generate text using the language model with streaming output.
    */
-  readonly streamText: <
-    Options extends NoExcessProperties<GenerateTextOptions<any>, Options>,
-    Tools extends Record<string, Tool.Any> = {}
-  >(
-    options: Options & GenerateTextOptions<Tools>
-  ) => Stream.Stream<
-    Response.StreamPart<Tools>,
-    ExtractError<Options>,
-    ExtractServices<Options>
-  >
+  readonly streamText: {
+    // No toolkit: force `{}` instead of falling back to `Record<string, Tool.Any>`.
+    <Options extends NoExcessProperties<GenerateTextOptionsWithoutToolkit, Options>>(
+      options: Options & GenerateTextOptionsWithoutToolkit
+    ): Stream.Stream<
+      Response.StreamPart<{}>,
+      ExtractError<Options>,
+      ExtractServices<Options>
+    >
+    // Generic toolkit: preserve caller-supplied `Tools` in helpers like `<Tools>(toolkit: WithHandler<Tools>) => ...`.
+    <
+      Tools extends Record<string, Tool.Any>,
+      Options extends NoExcessProperties<
+        GenerateTextOptions<Tools> & { readonly toolkit: ToolkitInput<Tools> },
+        Options
+      >
+    >(
+      options: Options & GenerateTextOptions<Tools> & { readonly toolkit: ToolkitInput<Tools> }
+    ): Stream.Stream<
+      Response.StreamPart<Tools>,
+      ExtractError<Options>,
+      ExtractServices<Options>
+    >
+    // Toolkit unions: recover distributive `ExtractTools<Options>` inference for `toolkitA | toolkitB` call sites.
+    <
+      Options extends {
+        readonly toolkit: ToolkitOption<any>
+      } & NoExcessProperties<GenerateTextOptions<any>, Options>
+    >(
+      options: Options & GenerateTextOptions<ExtractTools<Options>> & { readonly toolkit: Options["toolkit"] }
+    ): Stream.Stream<
+      Response.StreamPart<ExtractTools<Options>>,
+      ExtractError<Options>,
+      ExtractServices<Options>
+    >
+  }
 }
 
 /**
@@ -206,7 +258,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?: ToolkitOption<Tools> | undefined
+  readonly toolkit?: ToolkitInput<Tools> | undefined
 
   /**
    * The tool choice mode for the language model.
@@ -246,6 +298,10 @@ export interface GenerateTextOptions<Tools extends Record<string, Tool.Any>> {
   readonly disableToolCallResolution?: boolean | undefined
 }
 
+type GenerateTextOptionsWithoutToolkit = Omit<GenerateTextOptions<{}>, "toolkit"> & {
+  readonly toolkit?: undefined
+}
+
 /**
  * Configuration options for structured object generation.
  *
@@ -481,6 +537,30 @@ export type ToolkitOption<
   )
   : never
 
+/**
+ * The supported toolkit input shapes for language model operation options.
+ *
+ * Unlike `ToolkitOption`, this type does not distribute over unions. It is
+ * intended for call-site assignability, while `ToolkitOption` remains the
+ * distributive helper used for extraction and inference.
+ *
+ * @since 4.0.0
+ * @category utility types
+ */
+export type ToolkitInput<
+  Tools extends Record<string, Tool.Any>,
+  E = never,
+  R = any
+> =
+  | ToolkitOption<Tools, E, R>
+  | Toolkit.WithHandler<Tools>
+  | Effect.Yieldable<
+    Toolkit.Toolkit<Tools>,
+    Toolkit.WithHandler<Tools>,
+    E,
+    R
+  >
+
 type ExtractToolsFromToolkitOption<ToolkitValue> = ToolkitValue extends Toolkit.WithHandler<infer Tools> ? Tools
   : ToolkitValue extends Effect.Yieldable<
     Toolkit.Toolkit<infer Tools>,
@@ -1509,9 +1589,9 @@ export const make: (params: {
   }) as any
 
   return {
-    generateText,
+    generateText: generateText as Service["generateText"],
     generateObject,
-    streamText
+    streamText: streamText as Service["streamText"]
   } as const
 })
 
@@ -1543,27 +1623,49 @@ export const make: (params: {
  * @since 4.0.0
  * @category text generation
  */
-export function generateText<
-  Options extends NoExcessProperties<GenerateTextOptions<any>, Options>
->(
-  options: Options & GenerateTextOptions<ExtractTools<Options>>
-): Effect.Effect<
-  GenerateTextResponse<ExtractTools<Options>>,
-  ExtractError<Options>,
-  LanguageModel | ExtractServices<Options>
->
-export function generateText(
-  options: GenerateTextOptions<any>
-): Effect.Effect<
+export const generateText: {
+  // No toolkit: force `{}` instead of falling back to `Record<string, Tool.Any>`.
+  <
+    Options extends NoExcessProperties<GenerateTextOptionsWithoutToolkit, Options>
+  >(
+    options: Options & GenerateTextOptionsWithoutToolkit
+  ): Effect.Effect<
+    GenerateTextResponse<{}>,
+    ExtractError<Options>,
+    LanguageModel | ExtractServices<Options>
+  >
+  // Generic toolkit: preserve caller-supplied `Tools` in helpers like `<Tools>(toolkit: WithHandler<Tools>) => ...`.
+  <
+    Tools extends Record<string, Tool.Any>,
+    Options extends NoExcessProperties<GenerateTextOptions<Tools> & { readonly toolkit: ToolkitInput<Tools> }, Options>
+  >(
+    options: Options & GenerateTextOptions<Tools> & { readonly toolkit: ToolkitInput<Tools> }
+  ): Effect.Effect<
+    GenerateTextResponse<Tools>,
+    ExtractError<Options>,
+    LanguageModel | ExtractServices<Options>
+  >
+  // Toolkit unions: recover distributive `ExtractTools<Options>` inference for `toolkitA | toolkitB` call sites.
+  <
+    Options extends {
+      readonly toolkit: ToolkitOption<any>
+    } & NoExcessProperties<GenerateTextOptions<any>, Options>
+  >(
+    options: Options & GenerateTextOptions<ExtractTools<Options>> & { readonly toolkit: Options["toolkit"] }
+  ): Effect.Effect<
+    GenerateTextResponse<ExtractTools<Options>>,
+    ExtractError<Options>,
+    ExtractServices<Options> | LanguageModel
+  >
+} = (options: GenerateTextOptions<any>): Effect.Effect<
   GenerateTextResponse<any>,
   AiError.AiError,
   LanguageModel
-> {
-  return Effect.flatMap(
+> =>
+  Effect.flatMap(
     Effect.service(LanguageModel),
     (model) => model.generateText(options as any)
   )
-}
 
 /**
  * Generate a structured object from a schema using a language model.
@@ -1597,7 +1699,7 @@ export function generateText(
  * @since 4.0.0
  * @category object generation
  */
-export function generateObject<
+export const generateObject = <
   ObjectEncoded extends Record<string, any>,
   StructuredOutputSchema extends Schema.Encoder<ObjectEncoded, unknown>,
   Options extends NoExcessProperties<
@@ -1610,19 +1712,11 @@ export function generateObject<
   GenerateObjectResponse<ExtractTools<Options>, StructuredOutputSchema["Type"]>,
   ExtractError<Options>,
   ExtractServices<Options> | StructuredOutputSchema["DecodingServices"] | LanguageModel
->
-export function generateObject(
-  options: GenerateObjectOptions<any, Schema.Top>
-): Effect.Effect<
-  GenerateObjectResponse<any, any>,
-  AiError.AiError,
-  LanguageModel
-> {
-  return Effect.flatMap(
+> =>
+  Effect.flatMap(
     Effect.service(LanguageModel),
     (model) => model.generateObject(options as any)
   ) as any
-}
 
 /**
  * Generate text using a language model with streaming output.
@@ -1648,27 +1742,49 @@ export function generateObject(
  * @since 4.0.0
  * @category text generation
  */
-export function streamText<
-  Options extends NoExcessProperties<GenerateTextOptions<any>, Options>
->(
-  options: Options & GenerateTextOptions<ExtractTools<Options>>
-): Stream.Stream<
-  Response.StreamPart<ExtractTools<Options>>,
-  ExtractError<Options>,
-  ExtractServices<Options> | LanguageModel
->
-export function streamText(
-  options: GenerateTextOptions<any>
-): Stream.Stream<
-  Response.StreamPart<any>,
+export const streamText: {
+  // No toolkit: force `{}` instead of falling back to `Record<string, Tool.Any>`.
+  <
+    Options extends NoExcessProperties<GenerateTextOptionsWithoutToolkit, Options>
+  >(
+    options: Options & GenerateTextOptionsWithoutToolkit
+  ): Stream.Stream<
+    Response.StreamPart<{}>,
+    ExtractError<Options>,
+    ExtractServices<Options> | LanguageModel
+  >
+  // Generic toolkit: preserve caller-supplied `Tools` in helpers like `<Tools>(toolkit: WithHandler<Tools>) => ...`.
+  <
+    Tools extends Record<string, Tool.Any>,
+    Options extends NoExcessProperties<GenerateTextOptions<Tools> & { readonly toolkit: ToolkitInput<Tools> }, Options>
+  >(
+    options: Options & GenerateTextOptions<Tools> & { readonly toolkit: ToolkitInput<Tools> }
+  ): Stream.Stream<
+    Response.StreamPart<Tools>,
+    ExtractError<Options>,
+    ExtractServices<Options> | LanguageModel
+  >
+  // Toolkit unions: recover distributive `ExtractTools<Options>` inference for `toolkitA | toolkitB` call sites.
+  <
+    Options extends {
+      readonly toolkit: ToolkitOption<any>
+    } & NoExcessProperties<GenerateTextOptions<any>, Options>
+  >(
+    options: Options & GenerateTextOptions<ExtractTools<Options>> & { readonly toolkit: Options["toolkit"] }
+  ): Stream.Stream<
+    Response.StreamPart<ExtractTools<Options>>,
+    ExtractError<Options>,
+    ExtractServices<Options> | LanguageModel
+  >
+} = (options: GenerateTextOptions<any>): Stream.Stream<
+  Response.StreamPart<{}>,
   AiError.AiError,
   LanguageModel
-> {
-  return Stream.unwrap(Effect.map(
+> =>
+  Stream.unwrap(Effect.map(
     Effect.service(LanguageModel),
     (model) => model.streamText(options as any)
   )) as any
-}
 
 // =============================================================================
 // Tool Approval Helpers
@@ -2045,7 +2161,7 @@ const resolveToolCalls = <Tools extends Record<string, Tool.Any>>(
 // =============================================================================
 
 const resolveToolkit = <Tools extends Record<string, Tool.Any>, E, R>(
-  toolkit: ToolkitOption<Tools, E, R>
+  toolkit: ToolkitInput<Tools, E, R>
 ): Effect.Effect<Toolkit.WithHandler<Tools>, E, R> =>
   ("asEffect" in toolkit
     ? toolkit.asEffect()

package/src/unstable/ai/OpenAiStructuredOutput.ts

@@ -82,6 +82,9 @@ function rewriteOpenAI(schema: JsonSchema.JsonSchema): JsonSchema.JsonSchema {
       out[k] = v
     }
   }
+  if (out.type === "object" && out.properties === undefined && out.additionalProperties === false) {
+    out.properties = {}
+  }
   return out
 }
 

package/src/unstable/cli/Prompt.ts

@@ -2356,7 +2356,9 @@ const renderMultiSelectChoices = <A>(
       const annotatedCheckbox = isHighlighted && renderOptions?.plain !== true
         ? Ansi.annotate(checkbox, Ansi.cyanBright)
         : checkbox
-      const title = choice.title
+      const title = isHighlighted && renderOptions?.plain !== true
+        ? Ansi.annotate(choice.title, Ansi.cyanBright)
+        : choice.title
       const description = renderChoiceDescription(choice as SelectChoice<A>, isHighlighted, renderOptions)
       documents.push(prefix + " " + annotatedCheckbox + " " + title + " " + description)
     }

package/src/unstable/cli/internal/command.ts

@@ -8,6 +8,7 @@
 import * as Arr from "../../../Array.ts"
 import * as Effect from "../../../Effect.ts"
 import { YieldableProto } from "../../../internal/core.ts"
+import * as Option from "../../../Option.ts"
 import { pipeArguments } from "../../../Pipeable.ts"
 import * as Predicate from "../../../Predicate.ts"
 import * as ServiceMap from "../../../ServiceMap.ts"
@@ -228,11 +229,25 @@ export const toFlagDoc = (single: Param.Single<typeof Param.flagKind, unknown>):
     name: single.name,
     aliases: formattedAliases,
     type: single.typeName ?? Primitive.getTypeName(single.primitiveType),
-    description: single.description,
+    description: appendChoiceKeys(single.description, Primitive.getChoiceKeys(single.primitiveType)),
     required: single.primitiveType._tag !== "Boolean"
   }
 }
 
+const appendChoiceKeys = (
+  description: Option.Option<string>,
+  choiceKeys: ReadonlyArray<string> | undefined
+): Option.Option<string> => {
+  if (choiceKeys === undefined || choiceKeys.length === 0) {
+    return description
+  }
+  const choiceSuffix = `(choices: ${choiceKeys.join(", ")})`
+  return Option.match(description, {
+    onNone: () => Option.some(choiceSuffix),
+    onSome: (value) => Option.some(`${value} ${choiceSuffix}`)
+  })
+}
+
 /**
  * Creates a parser for a given config. Used as the default for both `parse`
  * and `parseContext`, and also by `withSharedFlags` to avoid constructing a

package/src/unstable/cluster/ClusterSchema.ts

@@ -1,9 +1,11 @@
 /**
  * @since 4.0.0
  */
-import { constFalse, constTrue } from "../../Function.ts"
+import { constFalse, constTrue, identity } from "../../Function.ts"
 import * as ServiceMap from "../../ServiceMap.ts"
+import type * as Rpc from "../rpc/Rpc.ts"
 import type { EntityId } from "./EntityId.ts"
+import type { Request } from "./Envelope.ts"
 
 /**
  * @since 4.0.0
@@ -13,6 +15,18 @@ export const Persisted = ServiceMap.Reference<boolean>("effect/cluster/ClusterSc
   defaultValue: constFalse
 })
 
+/**
+ * Whether to wrap the request with a storage transaction, so sql queries are
+ * committed atomically.
+ *
+ * @since 4.0.0
+ * @category Annotations
+ */
+export const WithTransaction = ServiceMap.Reference<boolean>(
+  "effect/cluster/ClusterSchema/WithTransaction",
+  { defaultValue: constFalse }
+)
+
 /**
  * @since 4.0.0
  * @category Annotations
@@ -56,3 +70,17 @@ export const ShardGroup = ServiceMap.Reference<(entityId: EntityId) => string>(
 export const ClientTracingEnabled = ServiceMap.Reference<boolean>("effect/cluster/ClusterSchema/ClientTracingEnabled", {
   defaultValue: constTrue
 })
+
+/**
+ * Dynamically transform the request annotations based on the request.
+ * This only applies to the requests handled by the Entity, not the client.
+ *
+ * @since 4.0.0
+ * @category Annotations
+ */
+export const Dynamic = ServiceMap.Reference<
+  (annotations: ServiceMap.ServiceMap<never>, request: Request<Rpc.AnyWithProps>) => ServiceMap.ServiceMap<never>
+>(
+  "effect/cluster/ClusterSchema/Dynamic",
+  { defaultValue: () => identity }
+)

package/src/unstable/cluster/ClusterWorkflowEngine.ts

@@ -6,6 +6,7 @@ import * as Duration from "../../Duration.ts"
 import * as Effect from "../../Effect.ts"
 import * as Exit from "../../Exit.ts"
 import * as Fiber from "../../Fiber.ts"
+import { constFalse } from "../../Function.ts"
 import * as Latch from "../../Latch.ts"
 import * as Layer from "../../Layer.ts"
 import * as Option from "../../Option.ts"
@@ -66,7 +67,9 @@ export const make = Effect.gen(function*() {
       | Rpc.Rpc<"deferred", Schema.Struct<{ name: typeof Schema.String; exit: typeof ExitUnknown }>, typeof ExitUnknown>
       | Rpc.Rpc<
         "activity",
-        Schema.Struct<{ name: typeof Schema.String; attempt: typeof Schema.Number }>,
+        Schema.Struct<
+          { name: typeof Schema.String; attempt: typeof Schema.Number; withTransaction: typeof Schema.Boolean }
+        >,
         Schema.declare<Workflow.Result<any, any>>
       >
       | Rpc.Rpc<"resume", Schema.Struct<{}>>
@@ -435,7 +438,13 @@ export const make = Effect.gen(function*() {
               activityLatches.delete(activityId)
             }
           }
-          const result = yield* Effect.orDie(client.activity({ name: activity.name, attempt }))
+          const result = yield* Effect.orDie(
+            client.activity({
+              name: activity.name,
+              attempt,
+              withTransaction: ServiceMap.get(activity.annotations, ClusterSchema.WithTransaction)
+            })
+          )
           // If the activity has suspended and did not execute, we need to resume
           // it by resetting the attempt and re-executing.
           if (result._tag === "Suspended" && (activities.has(activityId) || interruptedActivities.has(activityId))) {
@@ -532,7 +541,10 @@ const ExitUnknown = Schema.Exit(AnyOrVoid, AnyOrVoid, Schema.Any)
 const ActivityRpc = Rpc.make("activity", {
   payload: {
     name: Schema.String,
-    attempt: Schema.Number
+    attempt: Schema.Number,
+    withTransaction: Schema.Boolean.pipe(
+      Schema.withDecodingDefault(constFalse)
+    )
   },
   primaryKey: ({ attempt, name }) => activityPrimaryKey(name, attempt),
   success: Workflow.Result({
@@ -541,6 +553,13 @@ const ActivityRpc = Rpc.make("activity", {
   })
 })
   .annotate(ClusterSchema.Persisted, true)
+  .annotate(
+    ClusterSchema.Dynamic,
+    (annotations, request) =>
+      (request.payload as any).withTransaction
+        ? ServiceMap.add(annotations, ClusterSchema.WithTransaction, true)
+        : annotations
+  )
 
 const DeferredRpc = Rpc.make("deferred", {
   payload: {

package/src/unstable/cluster/Entity.ts

@@ -608,6 +608,7 @@ export const keepAlive: (
   olatch.value.closeUnsafe()
   yield* Effect.orDie(sharding.sendOutgoing(
     new Message.OutgoingRequest({
+      annotations: ServiceMap.empty(),
       rpc: KeepAliveRpc,
       services: ServiceMap.empty() as any,
       envelope: Envelope.makeRequest({

package/src/unstable/cluster/Message.ts

@@ -5,10 +5,11 @@ import * as Data from "../../Data.ts"
 import * as Effect from "../../Effect.ts"
 import * as Option from "../../Option.ts"
 import * as Schema from "../../Schema.ts"
-import type { ServiceMap } from "../../ServiceMap.ts"
+import * as ServiceMap from "../../ServiceMap.ts"
 import * as Rpc from "../rpc/Rpc.ts"
 import type { PersistenceError } from "./ClusterError.ts"
 import { MalformedMessage } from "./ClusterError.ts"
+import * as ClusterSchema from "./ClusterSchema.ts"
 import type { EntityAddress } from "./EntityAddress.ts"
 import * as Envelope from "./Envelope.ts"
 import type * as Reply from "./Reply.ts"
@@ -35,6 +36,10 @@ export const incomingLocalFromOutgoing = <R extends Rpc.Any>(self: Outgoing<R>):
     return new IncomingEnvelope({ envelope: self.envelope })
   }
   return new IncomingRequestLocal({
+    annotations: ServiceMap.get(self.rpc.annotations, ClusterSchema.Dynamic)(
+      self.rpc.annotations,
+      self.envelope as any
+    ),
     envelope: self.envelope,
     respond: self.respond,
     lastSentReply: Option.none()
@@ -59,6 +64,7 @@ export class IncomingRequestLocal<R extends Rpc.Any> extends Data.TaggedClass("I
   readonly envelope: Envelope.Request<R>
   readonly lastSentReply: Option.Option<Reply.Reply<R>>
   readonly respond: (reply: Reply.Reply<R>) => Effect.Effect<void, MalformedMessage | PersistenceError>
+  readonly annotations: ServiceMap.ServiceMap<never>
 }> {}
 
 /**
@@ -82,10 +88,11 @@ export type Outgoing<R extends Rpc.Any> = OutgoingRequest<R> | OutgoingEnvelope
  */
 export class OutgoingRequest<R extends Rpc.Any> extends Data.TaggedClass("OutgoingRequest")<{
   readonly envelope: Envelope.Request<R>
-  readonly services: ServiceMap<Rpc.Services<R>>
+  readonly services: ServiceMap.ServiceMap<Rpc.Services<R>>
   readonly lastReceivedReply: Option.Option<Reply.Reply<R>>
   readonly rpc: R
   readonly respond: (reply: Reply.Reply<R>) => Effect.Effect<void>
+  readonly annotations: ServiceMap.ServiceMap<never>
 }> {
   /**
    * @since 4.0.0
@@ -191,15 +198,20 @@ export const deserializeLocal = <Rpc extends Rpc.Any>(
   return Schema.decodeEffect(Schema.toCodecJson(rpc.payloadSchema))(encoded.payload).pipe(
     Effect.provideServices(self.services),
     MalformedMessage.refail,
-    Effect.map((payload) =>
-      new IncomingRequestLocal({
-        envelope: Envelope.makeRequest({
-          ...encoded,
-          payload
-        } as any),
+    Effect.map((payload) => {
+      const envelope = Envelope.makeRequest({
+        ...encoded,
+        payload
+      } as any) as Envelope.Request<Rpc>
+      return new IncomingRequestLocal({
+        envelope,
         lastSentReply: Option.none(),
-        respond: self.respond
+        respond: self.respond,
+        annotations: ServiceMap.get(rpc.annotations, ClusterSchema.Dynamic)(
+          rpc.annotations,
+          envelope as any
+        )
       })
-    )
+    })
   ) as Effect.Effect<IncomingRequestLocal<Rpc>, MalformedMessage>
 }