effect 4.0.3 → 4.0.5

package/src/ai/Prompt.ts

@@ -2159,11 +2159,11 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
     return empty
   }
 
-  const assistantParts: Array<AssistantMessagePart> = []
+  const assistantParts: Array<AssistantMessagePart | undefined> = []
   const toolParts: Array<ToolMessagePart> = []
 
-  const activeTextDeltas = new Map<string, { text: string; options: ProviderOptions }>()
-  const activeReasoningDeltas = new Map<string, { text: string; options: ProviderOptions }>()
+  const activeTextDeltas = new Map<string, { index: number; text: string; options: ProviderOptions }>()
+  const activeReasoningDeltas = new Map<string, { index: number; text: string; options: ProviderOptions }>()
 
   for (const part of parts) {
     switch (part.type) {
@@ -2175,7 +2175,8 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
 
       // Text Parts (streaming)
       case "text-start": {
-        activeTextDeltas.set(part.id, { text: "", options: part.metadata })
+        activeTextDeltas.set(part.id, { index: assistantParts.length, text: "", options: part.metadata })
+        assistantParts.push(undefined)
         break
       }
       case "text-delta": {
@@ -2190,7 +2191,8 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
         if (activeTextDeltas.has(part.id)) {
           const active = activeTextDeltas.get(part.id)!
           active.options = mergeOptions(active.options, part.metadata)
-          assistantParts.push(makePart("text", active))
+          assistantParts[active.index] = makePart("text", { text: active.text, options: active.options })
+          activeTextDeltas.delete(part.id)
         }
         break
       }
@@ -2203,7 +2205,8 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
 
       // Reasoning Parts (streaming)
       case "reasoning-start": {
-        activeReasoningDeltas.set(part.id, { text: "", options: part.metadata })
+        activeReasoningDeltas.set(part.id, { index: assistantParts.length, text: "", options: part.metadata })
+        assistantParts.push(undefined)
         break
       }
       case "reasoning-delta": {
@@ -2218,7 +2221,8 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
         if (activeReasoningDeltas.has(part.id)) {
           const active = activeReasoningDeltas.get(part.id)!
           active.options = mergeOptions(active.options, part.metadata)
-          assistantParts.push(makePart("reasoning", active))
+          assistantParts[active.index] = makePart("reasoning", { text: active.text, options: active.options })
+          activeReasoningDeltas.delete(part.id)
         }
         break
       }
@@ -2272,14 +2276,24 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
     }
   }
 
-  if (assistantParts.length === 0 && toolParts.length === 0) {
+  // Keep partial text from unended blocks. Unended reasoning is dropped since it
+  // may lack the signature or encrypted content providers require for replay.
+  for (const active of activeTextDeltas.values()) {
+    if (active.text.length > 0) {
+      assistantParts[active.index] = makePart("text", { text: active.text, options: active.options })
+    }
+  }
+
+  const assistantContent = assistantParts.filter((part) => part !== undefined)
+
+  if (assistantContent.length === 0 && toolParts.length === 0) {
     return empty
   }
 
   const messages: Array<Message> = []
 
-  if (assistantParts.length > 0) {
-    messages.push(makeMessage("assistant", { content: assistantParts }))
+  if (assistantContent.length > 0) {
+    messages.push(makeMessage("assistant", { content: assistantContent }))
   }
 
   if (toolParts.length > 0) {

package/src/ai/Response.ts

@@ -441,16 +441,19 @@ export const StreamPart = <T extends Toolkit.Any | Toolkit.WithHandler<any>>(
 export type ToolCallParts<
   Tools extends Record<string, Tool.Any>,
   ParametersMode extends ToolParametersMode = "decoded"
-> = ToolCallPartForName<Tools, ParametersMode, keyof Tools>
+> = ParametersMode extends "deferred" ?
+  ToolCallPartForName<Tools, "opaque", keyof Tools> | ToolCallPart<string, unknown>
+  : ToolCallPartForName<Tools, ParametersMode, keyof Tools>
 
 /**
- * Controls whether tool parameters are decoded, encoded, or opaque.
+ * Controls tool parameter decoding. `"deferred"` allows undeclared tool names
+ * with opaque parameters, leaving validation to the caller.
  *
  * @stability unstable
  * @category utility types
  * @since 4.0.0
  */
-export type ToolParametersMode = "decoded" | "encoded" | "opaque"
+export type ToolParametersMode = "decoded" | "encoded" | "opaque" | "deferred"
 
 type ToolCallPartForName<
   Tools extends Record<string, Tool.Any>,

package/src/cli/Completions.ts

@@ -48,6 +48,11 @@ export interface FlagDescriptor {
   readonly aliases: ReadonlyArray<string>
   readonly description: string | undefined
   readonly type: FlagType
+  /**
+   * Whether the flag's value is optional. Its value can only be attached with
+   * `=` (`--name=value`), never given as the next word.
+   */
+  readonly optionalValue?: boolean | undefined
 }
 
 /**

package/src/cli/Flag.ts

@@ -611,6 +611,107 @@ export const withDescription: {
   <A>(self: Flag<A>, description: string): Flag<A>
 } = dual(2, <A>(self: Flag<A>, description: string) => Param.withDescription(self, description))
 
+/**
+ * Lets a flag be given without a value, in which case `value` is used.
+ *
+ * **Details**
+ *
+ * Follows GNU-style optional values, like `--color[=WHEN]`. An explicit value
+ * must be attached with `=` (`--watch=until-done` or `-w=until-done`). A bare
+ * `--watch` is parsed as `--watch=<value>`, so `value` is validated like any
+ * other input. The flag never consumes the next token, so in `--watch build`,
+ * `build` stays a positional argument or subcommand. The flag is still
+ * required unless it is made optional or given a default.
+ *
+ * **Example** (Flag with an optional value)
+ *
+ * ```ts import.meta.vitest
+ * import { Flag } from "effect/cli"
+ *
+ * const watch = Flag.Literals("watch", ["first-failure", "until-done"]).pipe(
+ *   Flag.withOptionalValue("first-failure"),
+ *   Flag.optional
+ * )
+ * // --watch             => Option.some("first-failure")
+ * // --watch=until-done  => Option.some("until-done")
+ * // (absent)            => Option.none()
+ * // In help: --watch [=choice]
+ * watch.kind // => "flag"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const withOptionalValue: {
+  /**
+   * Lets a flag be given without a value, in which case `value` is used.
+   *
+   * **Details**
+   *
+   * Follows GNU-style optional values, like `--color[=WHEN]`. An explicit value
+   * must be attached with `=` (`--watch=until-done` or `-w=until-done`). A bare
+   * `--watch` is parsed as `--watch=<value>`, so `value` is validated like any
+   * other input. The flag never consumes the next token, so in `--watch build`,
+   * `build` stays a positional argument or subcommand. The flag is still
+   * required unless it is made optional or given a default.
+   *
+   * **Example** (Flag with an optional value)
+   *
+   * ```ts import.meta.vitest
+   * import { Flag } from "effect/cli"
+   *
+   * const watch = Flag.Literals("watch", ["first-failure", "until-done"]).pipe(
+   *   Flag.withOptionalValue("first-failure"),
+   *   Flag.optional
+   * )
+   * // --watch             => Option.some("first-failure")
+   * // --watch=until-done  => Option.some("until-done")
+   * // (absent)            => Option.none()
+   * // In help: --watch [=choice]
+   * watch.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  (value: string): <A>(self: Flag<A>) => Flag<A>
+  /**
+   * Lets a flag be given without a value, in which case `value` is used.
+   *
+   * **Details**
+   *
+   * Follows GNU-style optional values, like `--color[=WHEN]`. An explicit value
+   * must be attached with `=` (`--watch=until-done` or `-w=until-done`). A bare
+   * `--watch` is parsed as `--watch=<value>`, so `value` is validated like any
+   * other input. The flag never consumes the next token, so in `--watch build`,
+   * `build` stays a positional argument or subcommand. The flag is still
+   * required unless it is made optional or given a default.
+   *
+   * **Example** (Flag with an optional value)
+   *
+   * ```ts import.meta.vitest
+   * import { Flag } from "effect/cli"
+   *
+   * const watch = Flag.Literals("watch", ["first-failure", "until-done"]).pipe(
+   *   Flag.withOptionalValue("first-failure"),
+   *   Flag.optional
+   * )
+   * // --watch             => Option.some("first-failure")
+   * // --watch=until-done  => Option.some("until-done")
+   * // (absent)            => Option.none()
+   * // In help: --watch [=choice]
+   * watch.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  <A>(self: Flag<A>, value: string): Flag<A>
+} = dual(2, <A>(self: Flag<A>, value: string) => Param.withOptionalValue(self, value))
+
 // -------------------------------------------------------------------------------------
 // metadata
 // -------------------------------------------------------------------------------------

package/src/cli/Param.ts

@@ -213,6 +213,10 @@ export interface Single<Kind extends ParamKind, out A> extends Param<Kind, A> {
   readonly primitiveType: Primitive.Primitive<A>
   readonly typeName?: string | undefined
   readonly hidden: boolean
+  /**
+   * Raw value used for a bare flag. See `withOptionalValue`.
+   */
+  readonly optionalValue?: string | undefined
 }
 
 /**
@@ -362,6 +366,7 @@ export const makeSingle = <const Kind extends ParamKind, A>(params: {
   readonly description?: Option.Option<string> | undefined
   readonly aliases?: ReadonlyArray<string> | undefined
   readonly hidden?: boolean | undefined
+  readonly optionalValue?: string | undefined
 }): Single<Kind, A> => {
   const parse: Parse<A> = (args) =>
     params.kind === argumentKind
@@ -2664,6 +2669,97 @@ export const withMetavar: {
       typeName: metavar
     })))
 
+/**
+ * Lets a flag be given without a value, in which case `value` is used.
+ *
+ * **Details**
+ *
+ * Follows GNU-style optional values. An explicit value must be attached with
+ * `=` (`--watch=until-done`), and a bare `--watch` is parsed as
+ * `--watch=<value>`. The flag never consumes the next token. It is still
+ * required unless it is made optional or given a default.
+ *
+ * **Example** (Flag with an optional value)
+ *
+ * ```ts import.meta.vitest
+ * import { Param } from "effect/cli"
+ *
+ * const watch = Param.String(Param.flagKind, "watch").pipe(
+ *   Param.withOptionalValue("first-failure"),
+ *   Param.optional
+ * )
+ * watch.kind // => "flag"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const withOptionalValue: {
+  /**
+   * Lets a flag be given without a value, in which case `value` is used.
+   *
+   * **Details**
+   *
+   * Follows GNU-style optional values. An explicit value must be attached with
+   * `=` (`--watch=until-done`), and a bare `--watch` is parsed as
+   * `--watch=<value>`. The flag never consumes the next token. It is still
+   * required unless it is made optional or given a default.
+   *
+   * **Example** (Flag with an optional value)
+   *
+   * ```ts import.meta.vitest
+   * import { Param } from "effect/cli"
+   *
+   * const watch = Param.String(Param.flagKind, "watch").pipe(
+   *   Param.withOptionalValue("first-failure"),
+   *   Param.optional
+   * )
+   * watch.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  (value: string): <A>(self: Param<typeof flagKind, A>) => Param<typeof flagKind, A>
+  /**
+   * Lets a flag be given without a value, in which case `value` is used.
+   *
+   * **Details**
+   *
+   * Follows GNU-style optional values. An explicit value must be attached with
+   * `=` (`--watch=until-done`), and a bare `--watch` is parsed as
+   * `--watch=<value>`. The flag never consumes the next token. It is still
+   * required unless it is made optional or given a default.
+   *
+   * **Example** (Flag with an optional value)
+   *
+   * ```ts import.meta.vitest
+   * import { Param } from "effect/cli"
+   *
+   * const watch = Param.String(Param.flagKind, "watch").pipe(
+   *   Param.withOptionalValue("first-failure"),
+   *   Param.optional
+   * )
+   * watch.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  <A>(self: Param<typeof flagKind, A>, value: string): Param<typeof flagKind, A>
+} = dual(2, <A>(
+  self: Param<typeof flagKind, A>,
+  value: string
+) =>
+  transformSingle(self, (single) =>
+    makeSingle({
+      ...single,
+      optionalValue: value
+    })))
+
 /**
  * Validates parsed values against a Schema, providing detailed error messages.
  *

package/src/cli/internal/command.ts

@@ -242,10 +242,11 @@ export const toFlagDoc = (
   metadata: ReturnType<typeof Param.getParamMetadata>
 ): FlagDoc => {
   const formattedAliases = single.aliases.map((alias) => alias.length === 1 ? `-${alias}` : `--${alias}`)
+  const type = single.typeName ?? Primitive.getTypeName(single.primitiveType)
   return {
     name: single.name,
     aliases: formattedAliases,
-    type: single.typeName ?? Primitive.getTypeName(single.primitiveType),
+    type: single.optionalValue === undefined ? type : `[=${type}]`,
     description: appendChoiceKeys(single.description, Primitive.getChoiceKeys(single.primitiveType)),
     required: single.primitiveType._tag !== "Boolean" && !metadata.isOptional
   }

package/src/cli/internal/completions/bash.ts

@@ -7,6 +7,7 @@
  * @internal
  */
 import type * as Completions from "../../Completions.ts"
+import { takesSeparateValue } from "./descriptor.ts"
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -164,7 +165,7 @@ const generateFunction = (
   lines.push(``)
 
   // Build flag-value dispatch
-  const flagsWithValues = descriptor.flags.filter((f) => f.type._tag !== "Boolean")
+  const flagsWithValues = descriptor.flags.filter(takesSeparateValue)
   if (flagsWithValues.length > 0) {
     lines.push(`  # Flag value completions`)
     lines.push(`  case "$prev" in`)
@@ -196,7 +197,7 @@ const generateFunction = (
     lines.push(`    fi`)
     lines.push(`    case "\${words[i]}" in`)
     for (const flag of descriptor.flags) {
-      if (flag.type._tag === "Boolean") continue
+      if (!takesSeparateValue(flag)) continue
       const forms = flagNamesForWordlist(flag)
       lines.push(`      ${forms.join("|")}) _skip_next=1 ;;`)
       lines.push(`      ${forms.map((form) => `${form}=*`).join("|")}) ;;`)
@@ -248,7 +249,7 @@ const generateFunction = (
     lines.push(`      --) _end_of_options=1 ;;`)
     for (const flag of descriptor.flags) {
       const forms = flagNamesForWordlist(flag)
-      if (flag.type._tag === "Boolean") {
+      if (!takesSeparateValue(flag)) {
         lines.push(`      ${forms.join("|")}) ;;`)
       } else {
         lines.push(`      ${forms.join("|")}) _skip_next=1 ;;`)

package/src/cli/internal/completions/descriptor.ts

@@ -95,7 +95,8 @@ export const fromCommand = (
         name: single.name,
         aliases: single.aliases,
         description: Option.getOrUndefined(single.description),
-        type: toFlagType(single as Param.Single<"flag", unknown>)
+        type: toFlagType(single as Param.Single<"flag", unknown>),
+        optionalValue: single.optionalValue !== undefined
       })
     }
   }
@@ -139,3 +140,11 @@ export const fromCommand = (
     subcommands
   }
 }
+
+/**
+ * Whether the flag reads its value from the next word.
+ *
+ * @internal
+ */
+export const takesSeparateValue = (flag: Completions.FlagDescriptor): boolean =>
+  flag.type._tag !== "Boolean" && flag.optionalValue !== true

package/src/cli/internal/completions/fish.ts

@@ -7,6 +7,7 @@
  * @internal
  */
 import type * as Completions from "../../Completions.ts"
+import { takesSeparateValue } from "./descriptor.ts"
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -88,7 +89,7 @@ const flagCompletionArgs = (flag: Completions.FlagDescriptor): Array<string> =>
   if (flag.description) {
     args.push(`-d '${escapeFishString(flag.description)}'`)
   }
-  const valueArgs = flagValueArgs(flag.type)
+  const valueArgs = takesSeparateValue(flag) ? flagValueArgs(flag.type) : undefined
   if (valueArgs) {
     args.push(valueArgs)
   }
@@ -159,8 +160,7 @@ const generateCompletions = (
 
   // Flag completions
   for (const flag of descriptor.flags) {
-    const isBoolean = flag.type._tag === "Boolean"
-    const dedup = isBoolean ? flagContainsOptCondition(flag) : valueFlagDedupCondition(flag)
+    const dedup = takesSeparateValue(flag) ? valueFlagDedupCondition(flag) : flagContainsOptCondition(flag)
     const flagCondition = condition ? `${condition}; and ${dedup}` : dedup
     const flagCondArg = flagCondition ? `-n '${flagCondition}'` : ``
 
@@ -170,7 +170,7 @@ const generateCompletions = (
     lines.push(parts.join(" "))
 
     // Boolean negation
-    if (isBoolean) {
+    if (flag.type._tag === "Boolean") {
       const negParts = [`complete -c ${executableName}`]
       if (flagCondArg) negParts.push(flagCondArg)
       negParts.push(`-l no-${flag.name}`)

package/src/cli/internal/completions/powershell.ts

@@ -48,7 +48,9 @@ const valueFields = (type: Completions.FlagType | Completions.ArgumentType): str
 
 const flagEntry = (flag: Completions.FlagDescriptor): string =>
   `@{ name = ${quotePs(flag.name)}; forms = ${psArray(flagForms(flag))}; ` +
-  `takesValue = $${flag.type._tag !== "Boolean"}; ${valueFields(flag.type)}; ` +
+  `takesValue = $${flag.type._tag !== "Boolean"}; ` +
+  (flag.optionalValue === true ? `optionalValue = $true; ` : "") +
+  `${valueFields(flag.type)}; ` +
   `description = ${psOptional(flag.description)} }`
 
 const argumentEntry = (argument: Completions.ArgumentDescriptor): string =>
@@ -235,7 +237,8 @@ const completer = (dataName: string): string =>
           continue
         }
         $used[$flag.name] = $true
-        if (-not $hasValue) { $pending = $flag }
+        # A flag with an optional value only takes a value attached with '='.
+        if (-not $hasValue -and -not $flag.optionalValue) { $pending = $flag }
       }
       continue
     }

package/src/cli/internal/completions/zsh.ts

@@ -72,16 +72,20 @@ const argAction = (type: Completions.ArgumentType): string => {
 const flagSpecs = (flag: Completions.FlagDescriptor): Array<string> => {
   const specs: Array<string> = []
   const desc = flag.description ? `[${escapeZshExplanation(flag.description)}]` : ""
-  const action = valueAction(flag.type)
+  // An optional value must follow `=` in the same word (`--name=-`), and `::`
+  // marks it optional.
+  const optional = flag.optionalValue === true && flag.type._tag !== "Boolean"
+  const valueSuffix = optional ? "=-" : ""
+  const action = optional ? `:${valueAction(flag.type)}` : valueAction(flag.type)
   const excl = `(${allForms(flag).join(" ")})`
 
   // Primary long name
-  specs.push(`'${excl}--${flag.name}${desc}${action}'`)
+  specs.push(`'${excl}--${flag.name}${valueSuffix}${desc}${action}'`)
 
   // Aliases
   for (const alias of flag.aliases) {
     const prefix = alias.length === 1 ? "-" : "--"
-    specs.push(`'${excl}${prefix}${alias}${desc}${action}'`)
+    specs.push(`'${excl}${prefix}${alias}${valueSuffix}${desc}${action}'`)
   }
 
   // Boolean negation

package/src/cli/internal/parser.ts

@@ -425,8 +425,9 @@ const asBooleanLiteral = (token: Token | undefined): string | undefined =>
  *
  * Value resolution order:
  * 1. Inline value: --flag=value or -f=value
- * 2. Boolean special case: implicit "true" or explicit boolean literal
- * 3. Next token: consume following Value token if present
+ * 2. Optional value: the flag's configured value, without consuming a token
+ * 3. Boolean special case: implicit "true" or explicit boolean literal
+ * 4. Next token: consume following Value token if present
  */
 const consumeFlagValue = (
   cursor: TokenCursor,
@@ -465,7 +466,7 @@ const consumeFlagValueWithTokens = (
       }
     }
 
-    const literal = asBooleanLiteral(cursor.peek())
+    const literal = spec.optionalValue === undefined ? asBooleanLiteral(cursor.peek()) : undefined
     if (literal !== undefined) {
       const literalToken = cursor.take()
       return {
@@ -490,6 +491,14 @@ const consumeFlagValueWithTokens = (
     }
   }
 
+  if (spec.optionalValue !== undefined) {
+    return {
+      _tag: "Value",
+      value: spec.optionalValue,
+      tokens: []
+    }
+  }
+
   // Boolean flags: check for explicit literal or default to "true"
   if (Primitive.isBoolean(spec.primitiveType)) {
     const literal = asBooleanLiteral(cursor.peek())

package/src/cli/internal/wizard.ts

@@ -171,8 +171,9 @@ const promptParam = Effect.fnUntraced(
       return values
     }
     // Inline option-looking values so the lexer cannot interpret them as flags or the -- delimiter.
+    // Flags with an optional value only accept an inline value.
     return values.flatMap((value) =>
-      value.value.startsWith("-") && value.value.length > 1
+      single.optionalValue !== undefined || (value.value.startsWith("-") && value.value.length > 1)
         ? [commandLineArg(`--${single.name}=${value.value}`, `--${single.name}=${value.displayValue}`)]
         : [commandLineArg(`--${single.name}`), value]
     )