effect 4.0.5 → 4.0.7

package/src/ai/AiError.ts

@@ -341,6 +341,15 @@ export interface ContentPolicyErrorMetadata extends ProviderMetadata {}
  */
 export interface InvalidRequestErrorMetadata extends ProviderMetadata {}
 
+/**
+ * Provider-specific metadata attached to `InvalidResponseError`.
+ *
+ * @stability unstable
+ * @category configuration
+ * @since 4.1.0
+ */
+export interface InvalidResponseErrorMetadata extends ProviderMetadata {}
+
 /**
  * Provider-specific metadata attached to `InternalProviderError`.
  *
@@ -835,7 +844,59 @@ export class InternalProviderError extends Schema.Error<InternalProviderError>(
 }
 
 /**
- * Error indicating failure to parse or validate LLM output.
+ * Error indicating the provider response does not conform to the expected format.
+ *
+ * **Details**
+ *
+ * Invalid response errors are not retryable because retrying does not resolve an
+ * incompatible provider response format. Optional HTTP context can retain request
+ * and response details for diagnosis.
+ *
+ * @see {@link InvalidOutputError} for retryable model-generated output failures
+ * @stability unstable
+ * @category errors
+ * @since 4.1.0
+ */
+export class InvalidResponseError extends Schema.Error<InvalidResponseError>(
+  "effect/ai/AiError/InvalidResponseError"
+)({
+  _tag: Schema.tag("InvalidResponseError"),
+  description: Schema.String,
+  metadata: providerMetadataWithDefaults<InvalidResponseErrorMetadata>(),
+  http: Schema.optional(HttpContext)
+}) {
+  /**
+   * Marks `InvalidResponseError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.1.0
+   */
+  readonly [ReasonTypeId] = ReasonTypeId
+
+  /**
+   * Invalid response errors are not retryable because the response format is incompatible.
+   *
+   * @since 4.1.0
+   */
+  get isRetryable(): boolean {
+    return false
+  }
+
+  /**
+   * Creates an InvalidResponseError from a provider response schema error.
+   *
+   * @since 4.1.0
+   */
+  static fromSchemaError(error: Schema.SchemaError): InvalidResponseError {
+    return new InvalidResponseError({ description: error.message })
+  }
+
+  override get message(): string {
+    return `Invalid response: ${this.description}`
+  }
+}
+
+/**
+ * Error indicating failure to parse or validate model-generated output.
  *
  * **Details**
  *
@@ -903,9 +964,7 @@ export class InvalidOutputError extends Schema.Error<InvalidOutputError>(
    * @since 4.0.0
    */
   static fromSchemaError(error: Schema.SchemaError): InvalidOutputError {
-    return new InvalidOutputError({
-      description: error.message
-    })
+    return new InvalidOutputError({ description: error.message })
   }
 
   override get message(): string {
@@ -1520,6 +1579,7 @@ export type AiErrorReason =
   | AuthenticationError
   | ContentPolicyError
   | InvalidRequestError
+  | InvalidResponseError
   | InternalProviderError
   | NetworkError
   | InvalidOutputError
@@ -1557,6 +1617,7 @@ export const AiErrorReason: Schema.Union<[
   typeof AuthenticationError,
   typeof ContentPolicyError,
   typeof InvalidRequestError,
+  typeof InvalidResponseError,
   typeof InternalProviderError,
   typeof NetworkError,
   typeof InvalidOutputError,
@@ -1576,6 +1637,7 @@ export const AiErrorReason: Schema.Union<[
   AuthenticationError,
   ContentPolicyError,
   InvalidRequestError,
+  InvalidResponseError,
   InternalProviderError,
   NetworkError,
   InvalidOutputError,

package/src/ai/Chat.ts

@@ -18,8 +18,7 @@ import * as Duration from "../Duration.ts"
 import * as Effect from "../Effect.ts"
 import * as Layer from "../Layer.ts"
 import * as Option from "../Option.ts"
-import type { PersistenceError } from "../persistence/Persistence.ts"
-import { BackingPersistence } from "../persistence/Persistence.ts"
+import { BackingPersistence, PersistenceError } from "../persistence/Persistence.ts"
 import * as Predicate from "../Predicate.ts"
 import * as Ref from "../Ref.ts"
 import * as Schema from "../Schema.ts"
@@ -926,13 +925,19 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
         return yield* new ChatNotFoundError({ chatId })
       }
       // Decode the encoded previous history
-      const history = yield* decodeHistory(previousHistory)
+      const history = yield* decodeHistory(previousHistory).pipe(
+        Effect.mapError((cause) =>
+          new PersistenceError({
+            message: `Failed to decode persisted history for chat "${chatId}"`,
+            cause
+          })
+        )
+      )
       // Hydrate the chat history
       yield* Ref.set(chat.history, history)
       // Convert the chat to a persisted chat
       return yield* toPersisted(chatId, chat, ttl)
-    },
-    Effect.catchTag("SchemaError", Effect.die)
+    }
   )
 
   const get = Effect.fnUntraced(

package/src/ai/Decision.ts

@@ -1,13 +1,15 @@
 /**
  * Defines decisions that a `DecisionModel` answers over a single input.
  * Pair an input schema with named classification, rating, or probability
- * decisions using `make`, then answer them with `DecisionModel.decide`.
+ * decisions using `make`, then answer them with `DecisionModel.decide`, or
+ * with `DecisionModel.decideSettled` to keep valid answers when others fail.
  *
  * @see {@link make} for building a definition from an input schema and decisions
  *
  * @stability unstable
  * @since 4.0.0
  */
+import type * as Result from "../Result.ts"
 import type * as Schema from "../Schema.ts"
 
 /**
@@ -175,6 +177,52 @@ export type Answers<Decisions extends Record<string, Any>> = {
   readonly [K in keyof Decisions]: Answer<Decisions[K]>
 }
 
+/**
+ * Reason and description of the first failed answer validation check.
+ *
+ * **Details**
+ *
+ * - `"Missing"`: the provider returned no answer for the decision.
+ * - `"Refused"`: the provider declined to answer the decision.
+ * - `"Invalid"`: the answer has an invalid kind, value, confidence, or distribution.
+ * - `"NoDistribution"`: a classify or rate answer is otherwise valid but has
+ *   no probabilities.
+ *
+ * Except for refusals, `description` is the message `DecisionModel.decide`
+ * fails with for the same answer.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export interface Unanswered {
+  readonly _tag: "Unanswered"
+  readonly reason: "Missing" | "Refused" | "NoDistribution" | "Invalid"
+  readonly description: string
+}
+
+/**
+ * Validated answer or the reason the decision is unanswered.
+ *
+ * @see {@link Unanswered} for the failure reasons
+ *
+ * @stability unstable
+ * @category utility types
+ * @since 4.0.6
+ */
+export type Outcome<D extends Any> = Result.Result<Answer<D>, Unanswered>
+
+/**
+ * Settled results keyed by decision name.
+ *
+ * @stability unstable
+ * @category utility types
+ * @since 4.0.6
+ */
+export type Outcomes<Decisions extends Record<string, Any>> = {
+  readonly [K in keyof Decisions]: Outcome<Decisions[K]>
+}
+
 /**
  * Input schema and named decisions that run together in one provider call.
  *