@xandreed/plugin-models 0.13.0 → 0.15.0

package/dist/llm/prompt-cache.entity.functions.js

@@ -0,0 +1,73 @@
+import { Option, Result, Schema } from "effect";
+import { CachePosition, PromptCacheControl, PromptCacheError, PromptCacheSettings } from "./prompt-cache.entity.js";
+const error = (reason, message) => new PromptCacheError({ reason, message }), lifetime = (control) => control.ttl ?? "5m", callerControl = (control) => {
+  if (control === null || control === void 0)
+    return Result.succeed(Option.none());
+  const invalid = () => Result.fail(error("Control", "A prompt cache control must be ephemeral with an optional five-minute or one-hour lifetime."));
+  if (typeof control !== "object")
+    return invalid();
+  const prototype = Object.getPrototypeOf(control);
+  if (prototype !== Object.prototype && prototype !== null)
+    return invalid();
+  if ("toJSON" in control || !Object.hasOwn(control, "type") || "ttl" in control && !Object.hasOwn(control, "ttl") || !Reflect.ownKeys(control).every((key) => {
+    const field = Object.getOwnPropertyDescriptor(control, key);
+    return (key === "type" || key === "ttl") && field !== void 0 && field.enumerable && Object.hasOwn(field, "value");
+  }))
+    return invalid();
+  if (!Schema.is(PromptCacheControl)(control) || Result.isFailure(Schema.decodeUnknownResult(PromptCacheControl)(control, { onExcessProperty: "error" })))
+    return invalid();
+  return Result.succeed(Option.some(control));
+}, orderedLifetimes = (indexes, ttlAt) => {
+  const lifetimes = indexes.toSorted((left, right) => left - right).map(ttlAt), firstShort = lifetimes.indexOf("5m");
+  return firstShort === -1 || lifetimes.lastIndexOf("1h") < firstShort;
+};
+export const planBreakpoints = (input) => Result.gen(function* () {
+  const controls = yield* Result.all(input.positions.map((position) => CachePosition.match(position, {
+    Unmarked: () => Result.succeed(Option.none()),
+    Caller: (value) => callerControl(value.control),
+    Auto: () => Result.succeed(Option.none())
+  }))), callerTopLevel = yield* callerControl(input.callerTopLevel), callerIndexes = controls.flatMap((control, index) => Option.isSome(control) ? [index] : []);
+  if (!input.capability) {
+    if (callerIndexes.length > 0 || Option.isSome(callerTopLevel))
+      return yield* Result.fail(error("Capability", "This Messages endpoint does not support prompt cache controls."));
+    return { selectedAuto: [], topLevel: Option.none() };
+  }
+  const topLevel = Option.orElse(callerTopLevel, () => PromptCacheSettings.match(input.policy, {
+    Auto: () => Option.none(),
+    TopLevel: (value) => Option.some({ type: "ephemeral", ttl: value.ttl }),
+    Off: () => Option.none()
+  })), finalIndex = input.positions.length - 1;
+  if (Option.isSome(topLevel) && finalIndex < 0)
+    return yield* Result.fail(error("TopLevel", "A top-level prompt cache control needs a cacheable request block."));
+  const finalCaller = controls[finalIndex] ?? Option.none();
+  if (Option.isSome(topLevel) && Option.exists(finalCaller, (control) => lifetime(control) !== lifetime(topLevel.value)))
+    return yield* Result.fail(error("TopLevel", "The top-level prompt cache control must match the final block's lifetime."));
+  const occupied = Option.isSome(topLevel) && Option.isNone(finalCaller) ? [...callerIndexes, finalIndex] : callerIndexes;
+  if (occupied.length > 4)
+    return yield* Result.fail(error("Capacity", "A Messages request supports at most four effective prompt cache breakpoints."));
+  const autoTtl = PromptCacheSettings.match(input.policy, {
+    Auto: (value) => value.ttl,
+    TopLevel: (value) => value.ttl,
+    Off: () => "5m"
+  }), ttlAt = (index) => {
+    if (index === finalIndex && Option.isSome(topLevel))
+      return lifetime(topLevel.value);
+    return Option.match(controls[index] ?? Option.none(), { onNone: () => autoTtl, onSome: lifetime });
+  };
+  if (!orderedLifetimes(occupied, ttlAt))
+    return yield* Result.fail(error("TtlOrder", "Place one-hour prompt cache controls before five-minute controls."));
+  return { selectedAuto: PromptCacheSettings.match(input.policy, {
+    Auto: () => input.positions.flatMap((position, index) => CachePosition.match(position, {
+      Unmarked: () => [],
+      Caller: () => [],
+      Auto: (value) => [{ index, priority: value.priority }]
+    })).toSorted((left, right) => left.priority - right.priority || right.index - left.index).reduce((selected, candidate) => {
+      if (candidate.index === finalIndex && Option.isSome(topLevel))
+        return selected;
+      const next = [...occupied, ...selected, candidate.index];
+      return next.length <= 4 && orderedLifetimes(next, ttlAt) ? [...selected, candidate.index] : selected;
+    }, []),
+    TopLevel: () => [],
+    Off: () => []
+  }).toSorted((left, right) => left - right), topLevel };
+});

package/dist/llm/prompt-cache.entity.js

@@ -0,0 +1,27 @@
+import { Schema } from "effect";
+export const PromptCacheTtl = Schema.Literals(["5m", "1h"]), PromptCacheSettings = Schema.Union([
+  Schema.TaggedStruct("Auto", { ttl: PromptCacheTtl }),
+  Schema.TaggedStruct("TopLevel", { ttl: PromptCacheTtl }),
+  Schema.TaggedStruct("Off", {})
+]).pipe(Schema.toTaggedUnion("_tag")), PromptCacheControl = Schema.Struct({
+  type: Schema.Literal("ephemeral"),
+  ttl: Schema.optionalKey(PromptCacheTtl)
+}), CachePosition = Schema.Union([
+  Schema.TaggedStruct("Unmarked", {}),
+  Schema.TaggedStruct("Caller", { control: Schema.Unknown }),
+  Schema.TaggedStruct("Auto", { priority: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)) })
+]).pipe(Schema.toTaggedUnion("_tag")), BreakpointInput = Schema.Struct({
+  positions: Schema.Array(CachePosition),
+  policy: PromptCacheSettings,
+  capability: Schema.Boolean,
+  callerTopLevel: Schema.optionalKey(Schema.Unknown)
+}), BreakpointPlan = Schema.Struct({
+  selectedAuto: Schema.Array(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))).check(Schema.makeFilter((indexes) => indexes.every((index, offset) => offset === 0 || (indexes[offset - 1] ?? -1) < index) ? !0 : "automatic indexes must be strictly increasing")),
+  topLevel: Schema.OptionFromNullOr(PromptCacheControl)
+});
+
+export class PromptCacheError extends Schema.TaggedError()("PromptCacheError", {
+  reason: Schema.Literals(["Control", "Capability", "Capacity", "TtlOrder", "TopLevel"]),
+  message: Schema.String
+}) {
+}

package/dist/llm/provider-client.adapter.d.ts

@@ -0,0 +1,9 @@
+import { AnthropicClient } from "@effect/ai-anthropic";
+import { OpenAiClient } from "@effect/ai-openai";
+import type { ProviderFailureProtocol } from "./provider-failure.entity.js";
+/** Inspect decoded raw data before the SDK merges context overflow into a length cut. */
+export declare const withAnthropicFailures: (client: AnthropicClient.Service) => AnthropicClient.Service;
+/** The same raw error interception serves native Responses and its Codex transport. */
+export declare const withOpenAiFailures: (client: OpenAiClient.Service) => OpenAiClient.Service;
+/** The adapter protocol the provider classifier interprets, not the configured provider alias. */
+export declare const providerFailureProtocol: (route: "anthropic" | "openai-responses" | "openai-codex" | "compat") => ProviderFailureProtocol;

package/dist/llm/provider-client.adapter.js

@@ -0,0 +1,60 @@
+import { AnthropicClient } from "@effect/ai-anthropic";
+import { OpenAiClient } from "@effect/ai-openai";
+import { Effect, Exit, Match, Option, Predicate, Schema, Stream } from "effect";
+import { AiError } from "effect/ai";
+import { modelFailureMessageOf, stampAiErrorFailure } from "@xandreed/core";
+import { classifyProviderFailure } from "./provider-failure.entity.functions.js";
+import { ProviderFailureEvidence } from "./provider-failure.entity.js";
+import { completeSdkResponseAttempt, modelOutcomeOfExit, observeResponseUsage } from "./model-completion.adapter.js";
+const encodeBody = Schema.encodeUnknownEffect(Schema.fromJsonString(Schema.Json)), jsonObject = Schema.decodeUnknownOption(Schema.JsonObject), emptyUsage = {}, ofUsage = (value) => Option.getOrElse(jsonObject(value), () => emptyUsage), httpDetails = (response, body) => {
+  const url = URL.canParse(response.request.url) ? new URL(response.request.url) : new URL("https://provider.invalid/"), headers = Object.fromEntries(Object.entries(response.headers).filter(([key]) => ["request-id", "x-request-id", "retry-after"].includes(key)));
+  return {
+    request: { method: "POST", url: `${url.protocol}//${url.host}${url.pathname}`, urlParams: [], headers: {} },
+    response: { status: response.status, headers },
+    body
+  };
+}, nativeFailure = Effect.fnUntraced(function* (method, evidence, response, raw, requestId) {
+  const kind = Option.getOrElse(classifyProviderFailure(evidence), () => "Unknown"), body = yield* encodeBody(raw).pipe(Effect.orDie), http = httpDetails(response, body), metadata = evidence.protocol === "anthropic" ? { anthropic: { errorType: evidence.type ?? evidence.stopReason ?? null, requestId } } : { openai: { errorCode: evidence.code ?? null, errorType: evidence.type ?? null, requestId } }, description = modelFailureMessageOf(kind), reason = Match.value(kind).pipe(Match.when("Authentication", () => new AiError.AuthenticationError({ kind: "Unknown", description, metadata, http })), Match.when("Quota", () => new AiError.QuotaExhaustedError({ metadata, http })), Match.when("RateLimit", () => new AiError.RateLimitError({ metadata, http })), Match.when("InvalidResponse", () => new AiError.InvalidResponseError({ description, metadata, http })), Match.when("Transient", () => new AiError.InternalProviderError({ description, metadata, http })), Match.when("Timeout", () => new AiError.InternalProviderError({ description, metadata, http })), Match.when("Unknown", () => new AiError.UnknownError({ description, metadata, http })), Match.orElse(() => new AiError.InvalidRequestError({ description, metadata, http }))), error = stampAiErrorFailure(AiError.make({ module: "Models", method, reason }), kind);
+  yield* completeSdkResponseAttempt(response, { _tag: "Failed", failure: Option.some(kind) });
+  return error;
+}), requestIdOf = (response) => response.headers["request-id"] ?? response.headers["x-request-id"] ?? null;
+export const withAnthropicFailures = (client) => ({
+  ...client,
+  createMessage: (options) => client.createMessage(options).pipe(Effect.tap(([body, response]) => observeResponseUsage(response, body.usage, !0)), Effect.flatMap(([body, response]) => body.stop_reason === "model_context_window_exceeded" ? nativeFailure("createMessage", { protocol: "anthropic", status: response.status, stopReason: body.stop_reason }, response, body, requestIdOf(response)).pipe(Effect.flatMap(Effect.fail)) : completeSdkResponseAttempt(response, { _tag: "Completed" }).pipe(Effect.as([body, response])))),
+  createMessageStream: (options) => client.createMessageStream(options).pipe(Effect.map(([response, stream]) => [
+    response,
+    stream.pipe(Stream.mapAccumEffect(() => emptyUsage, (before, event) => Match.value(event).pipe(Match.when({ type: "error" }, (value) => nativeFailure("createMessageStream", {
+      protocol: "anthropic",
+      status: response.status,
+      type: value.error.type,
+      message: value.error.message
+    }, response, { event: value, usage: before }, value.request_id ?? requestIdOf(response)).pipe(Effect.flatMap(Effect.fail))), Match.when({ type: "message_start" }, (value) => {
+      const usage = ofUsage(value.message.usage);
+      return observeResponseUsage(response, value.message.usage, !1).pipe(Effect.andThen(value.message.stop_reason === "model_context_window_exceeded" ? nativeFailure("createMessageStream", { protocol: "anthropic", status: response.status, stopReason: value.message.stop_reason }, response, { event: value, usage }, requestIdOf(response)).pipe(Effect.flatMap(Effect.fail)) : Effect.succeed([usage, [event]])));
+    }), Match.when({ type: "message_delta" }, (value) => {
+      const usage = { ...before, ...Object.fromEntries(Object.entries(ofUsage(value.usage)).filter(([, count]) => count !== null)) };
+      return observeResponseUsage(response, value.usage, value.delta.stop_reason != null).pipe(Effect.andThen(value.delta.stop_reason === "model_context_window_exceeded" ? nativeFailure("createMessageStream", { protocol: "anthropic", status: response.status, stopReason: value.delta.stop_reason }, response, { event: value, usage }, requestIdOf(response)).pipe(Effect.flatMap(Effect.fail)) : Effect.succeed([usage, [event]])));
+    }), Match.when({ type: "message_stop" }, () => completeSdkResponseAttempt(response, { _tag: "Completed" }).pipe(Effect.as([before, [event]]))), Match.orElse(() => Effect.succeed([before, [event]])))), Stream.onEnd(completeSdkResponseAttempt(response, { _tag: "Completed" })), Stream.onExit((exit) => completeSdkResponseAttempt(response, Exit.isSuccess(exit) ? { _tag: "Interrupted" } : modelOutcomeOfExit(exit))))
+  ]))
+});
+const openAiFailure = (method, body, response, raw = body) => nativeFailure(method, {
+  protocol: "openai",
+  status: response.status,
+  ...body.error == null ? {} : { code: body.error.code, message: body.error.message }
+}, response, raw, requestIdOf(response));
+export const withOpenAiFailures = (client) => ({
+  ...client,
+  createResponse: (options) => client.createResponse(options).pipe(Effect.tap(([body, response]) => observeResponseUsage(response, body.usage, !0)), Effect.flatMap(([body, response]) => body.error != null ? openAiFailure("createResponse", body, response).pipe(Effect.flatMap(Effect.fail)) : completeSdkResponseAttempt(response, { _tag: "Completed" }).pipe(Effect.as([body, response])))),
+  createResponseStream: (options) => client.createResponseStream(options).pipe(Effect.map(([response, stream]) => [
+    response,
+    stream.pipe(Stream.mapAccumEffect(() => emptyUsage, (before, event) => {
+      const observed = Predicate.hasProperty(event, "response") && Predicate.hasProperty(event.response, "usage") ? ofUsage(event.response.usage) : emptyUsage, usage = { ...before, ...Object.fromEntries(Object.entries(observed).filter(([, count]) => count !== null)) }, raw = { event, usage }, final = event.type === "response.completed" || event.type === "response.failed" || event.type === "response.incomplete";
+      return observeResponseUsage(response, observed, final).pipe(Effect.andThen(Match.value(event).pipe(Match.when({ type: "error" }, (value) => nativeFailure("createResponseStream", {
+        protocol: "openai",
+        status: Schema.is(ProviderFailureEvidence.fields.status)(value.status) ? value.status : response.status,
+        ...value.code == null ? {} : { code: value.code },
+        message: value.message
+      }, response, raw, requestIdOf(response)).pipe(Effect.flatMap(Effect.fail))), Match.when({ type: "response.failed" }, (value) => openAiFailure("createResponseStream", value.response, response, raw).pipe(Effect.flatMap(Effect.fail))), Match.when({ response: { error: (error) => error != null } }, (value) => openAiFailure("createResponseStream", value.response, response, raw).pipe(Effect.flatMap(Effect.fail))), Match.orElse(() => (final ? completeSdkResponseAttempt(response, { _tag: "Completed" }) : Effect.void).pipe(Effect.as([usage, [event]]))))));
+    }), Stream.onEnd(completeSdkResponseAttempt(response, { _tag: "Completed" })), Stream.onExit((exit) => completeSdkResponseAttempt(response, Exit.isSuccess(exit) ? { _tag: "Interrupted" } : modelOutcomeOfExit(exit))))
+  ]))
+}), providerFailureProtocol = (route) => route === "anthropic" ? "anthropic" : route === "compat" ? "compat" : "openai";

package/dist/llm/provider-failure.entity.d.ts

@@ -0,0 +1,42 @@
+import { Schema } from "effect";
+/** The existing provider dialect whose error vocabulary is being interpreted. */
+export declare const ProviderFailureProtocol: Schema.Literals<readonly ["anthropic", "openai", "compat"]>;
+export type ProviderFailureProtocol = typeof ProviderFailureProtocol.Type;
+/** Raw provider evidence, before status and SDK normalization discard its meaning. */
+export declare const ProviderFailureEvidence: Schema.Struct<{
+    readonly protocol: Schema.Literals<readonly ["anthropic", "openai", "compat"]>;
+    readonly status: Schema.optionalKey<Schema.Int>;
+    readonly code: Schema.optionalKey<Schema.String>;
+    readonly type: Schema.optionalKey<Schema.String>;
+    readonly message: Schema.optionalKey<Schema.String>;
+    readonly stopReason: Schema.optionalKey<Schema.String>;
+}>;
+export type ProviderFailureEvidence = typeof ProviderFailureEvidence.Type;
+/** Only known structured error fields are read; arbitrary response data is not searched. */
+export declare const ProviderErrorDetail: Schema.Struct<{
+    readonly code: Schema.optionalKey<Schema.NullOr<Schema.Union<readonly [Schema.String, Schema.Number]>>>;
+    readonly type: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly message: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+}>;
+export type ProviderErrorDetail = typeof ProviderErrorDetail.Type;
+/** HTTP providers and sockets expose these two established error-body shapes. */
+export declare const ProviderErrorBody: Schema.Struct<{
+    readonly code: Schema.optionalKey<Schema.NullOr<Schema.Union<readonly [Schema.String, Schema.Number]>>>;
+    readonly type: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly message: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly error: Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
+        readonly code: Schema.optionalKey<Schema.NullOr<Schema.Union<readonly [Schema.String, Schema.Number]>>>;
+        readonly type: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+        readonly message: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    }>, Schema.String]>>;
+}>;
+export type ProviderErrorBody = typeof ProviderErrorBody.Type;
+/** The pinned SDK's namespaced HTTP metadata and top-level socket metadata. */
+export declare const ProviderErrorMetadata: Schema.Struct<{
+    readonly errorCode: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly errorType: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly code: Schema.optionalKey<Schema.NullOr<Schema.Union<readonly [Schema.String, Schema.Number]>>>;
+    readonly type: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly message: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+}>;
+export type ProviderErrorMetadata = typeof ProviderErrorMetadata.Type;

package/dist/llm/provider-failure.entity.functions.d.ts

@@ -0,0 +1,8 @@
+import { Option } from "effect";
+import type { AiError } from "effect/ai";
+import type { ModelFailureKind } from "@xandreed/core";
+import type { ProviderFailureEvidence, ProviderFailureProtocol } from "./provider-failure.entity.js";
+/** Interpret only supported provider evidence; absence is not a guessed failure kind. */
+export declare const classifyProviderFailure: (evidence: ProviderFailureEvidence) => Option.Option<ModelFailureKind>;
+/** Refine provider evidence without changing an error's concrete reason or unrelated fields. */
+export declare const classifyAiError: (error: AiError.AiError, protocol: ProviderFailureProtocol) => AiError.AiError;

package/dist/llm/provider-failure.entity.functions.js

@@ -0,0 +1,67 @@
+import { Option, Predicate, Schema } from "effect";
+import { ENGINE_KEY, ModelFailureStamp, modelFailureOf, stampAiErrorFailure } from "@xandreed/core";
+import { ProviderErrorBody, ProviderErrorMetadata } from "./provider-failure.entity.js";
+import { QUOTA_ERRORS } from "./chat-wire.entity.functions.js";
+const quotaNames = new Set([...QUOTA_ERRORS].map((name) => name.toLowerCase()).concat("insufficient_quota_error")), contextNames = new Set(["context_length_exceeded", "context_window_exceeded", "model_context_window_exceeded"]), authenticationNames = new Set(["authentication_error", "permission_error", "invalid_api_key", "invalid_api_key_error", "invalid_authentication"]), rateNames = new Set(["rate_limit_error", "rate_limit_exceeded", "rate_limit_exceeded_error"]), transientNames = new Set(["overloaded_error", "api_error", "server_error", "service_unavailable_error"]), timeoutNames = new Set(["request_timeout", "timeout_error"]), invalidNames = new Set(["modelerror", "not_found_error", "request_too_large", "request_too_large_error", "content_policy_violation", "content_policy_error"]), namedKinds = [
+  [contextNames, "ContextOverflow"],
+  [quotaNames, "Quota"],
+  [authenticationNames, "Authentication"],
+  [rateNames, "RateLimit"],
+  [transientNames, "Transient"],
+  [timeoutNames, "Timeout"],
+  [invalidNames, "InvalidRequest"]
+], namedFailure = (name) => Option.flatMap(Option.fromNullishOr(name), (value) => Option.map(Option.fromNullishOr(namedKinds.find(([names]) => names.has(value.toLowerCase()))), ([, kind]) => kind)), contextPatterns = {
+  anthropic: [/\b(?:input|prompt|request)\b.{0,80}\bexceeds? (?:the |this model's )?context window\b/i],
+  openai: [/\bmaximum context length is \d+ tokens\b/i, /\b(?:input|prompt|request)\b.{0,80}\bexceeds? (?:the |this model's )?context window\b/i],
+  compat: [/\bmaximum context length is \d+ tokens\b/i, /\b(?:input|prompt|request)\b.{0,80}\bexceeds? (?:the |this model's )?context window\b/i]
+};
+export const classifyProviderFailure = (evidence) => {
+  if (evidence.protocol === "anthropic" && evidence.stopReason === "model_context_window_exceeded")
+    return Option.some("ContextOverflow");
+  const specific = Option.orElse(namedFailure(evidence.code), () => namedFailure(evidence.type));
+  if (Option.isSome(specific))
+    return specific;
+  const message = evidence.message ?? "", contextMessage = contextPatterns[evidence.protocol].some((pattern) => pattern.test(message)) || evidence.protocol !== "openai" && evidence.status !== 413 && /\bprompt (?:is )?too long\b/i.test(message);
+  if ([evidence.code, evidence.type].some((name) => name?.toLowerCase() === "invalid_request_error"))
+    return Option.some(contextMessage ? "ContextOverflow" : "InvalidRequest");
+  if (/\bmodel .*not supported\b/i.test(message))
+    return Option.some("InvalidRequest");
+  if (evidence.status === 402)
+    return Option.some("Quota");
+  if (evidence.status === 401 || evidence.status === 403)
+    return Option.some("Authentication");
+  if ((evidence.status === void 0 || [200, 400, 413, 422].includes(evidence.status)) && contextMessage)
+    return Option.some("ContextOverflow");
+  if (evidence.status === 429)
+    return Option.some("RateLimit");
+  if (evidence.status === 408 || evidence.status === 504)
+    return Option.some("Timeout");
+  if (evidence.status !== void 0 && evidence.status >= 500)
+    return Option.some("Transient");
+  if (evidence.status !== void 0 && evidence.status >= 400)
+    return Option.some("InvalidRequest");
+  return Option.none();
+}, classifyAiError = (error, protocol) => {
+  const reason = error.reason, metadata = "metadata" in reason ? reason.metadata : {}, engine = Object.hasOwn(metadata, ENGINE_KEY) ? metadata[ENGINE_KEY] : void 0;
+  if (Predicate.isObject(engine) && Object.hasOwn(engine, "failure") && Option.isSome(Schema.decodeUnknownOption(ModelFailureStamp)(engine)))
+    return error;
+  if (reason._tag === "InvalidOutputError" && (protocol === "anthropic" && error.module === "AnthropicClient" && ["createMessage", "createMessageStream"].includes(error.method) || protocol === "openai" && error.module === "OpenAiClient"))
+    return stampAiErrorFailure(error, "InvalidResponse");
+  if (Option.isNone(modelFailureOf(error)) || reason._tag === "NetworkError")
+    return error;
+  const http = "http" in reason ? reason.http : void 0, body = Option.flatMap(Option.fromNullishOr(http?.body), Schema.decodeUnknownOption(Schema.fromJsonString(ProviderErrorBody))), namespace = protocol === "compat" ? error.module : protocol, provider = Schema.decodeUnknownOption(ProviderErrorMetadata)(Object.hasOwn(metadata, namespace) ? metadata[namespace] : {}), socket = Schema.decodeUnknownOption(ProviderErrorMetadata)(metadata), details = [
+    ...Option.toArray(Option.map(body, (value) => typeof value.error === "string" ? { message: value.error } : value.error ?? value)),
+    ...Option.toArray(Option.map(provider, (value) => ({ ...value, ...value.errorCode == null ? {} : { code: value.errorCode }, ...value.errorType == null ? {} : { type: value.errorType } }))),
+    ...Option.toArray(socket)
+  ], field = (key) => Option.fromNullishOr(details.flatMap((detail) => {
+    const value = detail[key];
+    return typeof value === "string" ? [value] : [];
+  })[0]), evidence = {
+    protocol,
+    ...http?.response === void 0 ? {} : { status: http.response.status },
+    ...Option.match(field("code"), { onNone: () => ({}), onSome: (code) => ({ code }) }),
+    ...Option.match(field("type"), { onNone: () => ({}), onSome: (type) => ({ type }) }),
+    message: Option.getOrElse(field("message"), () => reason.message)
+  };
+  return Option.match(classifyProviderFailure(evidence), { onNone: () => error, onSome: (kind) => stampAiErrorFailure(error, kind) });
+};

package/dist/llm/provider-failure.entity.js

@@ -0,0 +1,20 @@
+import { Schema } from "effect";
+export const ProviderFailureProtocol = Schema.Literals(["anthropic", "openai", "compat"]), ProviderFailureEvidence = Schema.Struct({
+  protocol: ProviderFailureProtocol,
+  status: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 100, maximum: 599 }))),
+  code: Schema.optionalKey(Schema.String),
+  type: Schema.optionalKey(Schema.String),
+  message: Schema.optionalKey(Schema.String),
+  stopReason: Schema.optionalKey(Schema.String)
+}), ProviderErrorDetail = Schema.Struct({
+  code: Schema.optionalKey(Schema.NullOr(Schema.Union([Schema.String, Schema.Number]))),
+  type: Schema.optionalKey(Schema.NullOr(Schema.String)),
+  message: Schema.optionalKey(Schema.NullOr(Schema.String))
+}), ProviderErrorBody = Schema.Struct({
+  error: Schema.optionalKey(Schema.Union([ProviderErrorDetail, Schema.String])),
+  ...ProviderErrorDetail.fields
+}), ProviderErrorMetadata = Schema.Struct({
+  ...ProviderErrorDetail.fields,
+  errorCode: Schema.optionalKey(Schema.NullOr(Schema.String)),
+  errorType: Schema.optionalKey(Schema.NullOr(Schema.String))
+});

package/dist/llm/provider-profile.entity.d.ts

@@ -0,0 +1,79 @@
+import { Schema } from "effect";
+import type { Option } from "effect";
+import type { ModelLimits, ReasoningEffortType } from "@xandreed/core";
+/** Documented native controls, or an explicitly labelled family policy for future IDs. */
+export declare const AnthropicModelTraits: Schema.Struct<{
+    readonly source: Schema.Literals<readonly ["documented", "family-policy"]>;
+    readonly modes: Schema.$Array<Schema.Literals<readonly ["Adaptive", "Budget", "BetweenTools", "Off"]>>;
+    readonly defaultThinking: Schema.OptionFromNullOr<Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Adaptive", {
+        readonly display: Schema.optionalKey<Schema.Literals<readonly ["summarized", "omitted"]>>;
+    }>, Schema.TaggedStruct<"Budget", {
+        readonly budgetTokens: Schema.Int;
+        readonly display: Schema.optionalKey<Schema.Literals<readonly ["summarized", "omitted"]>>;
+    }>, Schema.TaggedStruct<"BetweenTools", {}>, Schema.TaggedStruct<"Off", {}>]>>;
+    readonly defaultEffort: Schema.OptionFromNullOr<Schema.Literals<readonly ["low", "medium", "high", "xhigh", "max"]>>;
+    readonly forcedTools: Schema.OptionFromNullOr<Schema.Boolean>;
+    readonly reducedEfforts: Schema.OptionFromNullOr<Schema.$Array<Schema.Literals<readonly ["low", "medium", "high", "xhigh", "max"]>>>;
+}>;
+export type AnthropicModelTraits = typeof AnthropicModelTraits.Type;
+/** The providers the models plugin builds itself; any other is a configured endpoint. */
+export declare const BuiltInProvider: Schema.Literals<readonly ["opencode", "openai-codex", "openai", "anthropic", "google"]>;
+export type BuiltInProvider = typeof BuiltInProvider.Type;
+/** The OpenAI Responses API, at `apiUrl` (the SDK's own by default). */
+export interface ResponsesRoute {
+    readonly _tag: "openai-responses";
+    readonly apiUrl: Option.Option<string>;
+    /** Sent as the model's `strictJsonSchema` option; none: the SDK's default. */
+    readonly strictJsonSchema: Option.Option<boolean>;
+    /** Whose calls carry the call policy's effort: every model's, or only a model's that lists efforts (a non-reasoning model refuses one). */
+    readonly effort: "always" | "listed";
+}
+/** An OpenAI-compatible gateway's chat completions. */
+export interface ChatRoute {
+    readonly _tag: "compat";
+    /** The client's name in its failures. */
+    readonly moduleName: string;
+    readonly chatUrl: string;
+    /** Standard chat-completions fields only (`CompatConfig.standardOnly`). */
+    readonly standardOnly: boolean;
+    /** Whether the reasoning tokens are read (`UsageReading`). */
+    readonly usage: {
+        readonly reasoning: boolean;
+    };
+}
+/**
+ * The wire a built-in model is sent over (its `_tag`), with what its client
+ * needs beyond the model and the key: Anthropic's Messages API, the OpenAI
+ * Responses API, the subscription's Codex dialect of it, or a gateway's chat
+ * completions.
+ */
+export type Route = {
+    readonly _tag: "anthropic";
+} | ResponsesRoute | {
+    readonly _tag: "openai-codex";
+} | ChatRoute;
+/** A model of a built-in provider: whether its route sends it images (where not, they go as label lines), the efforts it takes, and whether its thinking is bound to the conversation. */
+export interface ModelProfile {
+    readonly id: string;
+    readonly images: boolean;
+    readonly efforts: ReadonlyArray<ReasoningEffortType>;
+    readonly limits?: ModelLimits;
+    readonly anthropic?: AnthropicModelTraits;
+    /**
+     * The provider binds each thinking block's signature to the conversation
+     * before it (system, tools, earlier messages): a block sent back after that
+     * prefix changed is refused, unless the request says what to do with it
+     * (the models plugin's `thinkingPrefixMismatch`).
+     */
+    readonly bindsThinking: boolean;
+}
+/** One built-in provider: its catalog, what each model reads and takes, and the route each is sent over. */
+export interface ProviderProfile {
+    /** The catalog's name for the provider's route, before ` · <model>`; none: its entries have no label. */
+    readonly label: Option.Option<string>;
+    /** The catalog: the models the provider lists, in order. */
+    readonly models: ReadonlyArray<ModelProfile>;
+    /** A model's profile, listed or not: one the catalog does not list follows its family. */
+    readonly modelOf: (modelId: string) => ModelProfile;
+    readonly routeOf: (modelId: string) => Route;
+}

package/dist/llm/provider-profile.entity.functions.d.ts

@@ -0,0 +1,23 @@
+import { Option } from "effect";
+import { BuiltInProvider } from "./provider-profile.entity.js";
+import type { ModelProfile, ProviderProfile } from "./provider-profile.entity.js";
+/**
+ * The built-in providers, one profile each. The catalog, the image and
+ * effort flags and the route builders read this table instead of naming a
+ * provider.
+ */
+export declare const OPENCODE_CHAT_URL = "https://opencode.ai/zen/go/v1/chat/completions";
+/** OpenCode serves GPT models through the OpenAI Responses protocol. */
+export declare const OPENCODE_RESPONSES_API_URL = "https://opencode.ai/zen/v1";
+/** Gemini through its OpenAI-compatible chat completions (Bearer API key). */
+export declare const GOOGLE_CHAT_URL = "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions";
+/** Model-ID traits work for a configured Messages gateway as well as the builtin provider. */
+export declare const anthropicProfileOf: (modelId: string) => ModelProfile;
+/** Every built-in provider's profile, in the catalog's order of providers. */
+export declare const PROVIDER_PROFILES: {
+    readonly [P in BuiltInProvider]: ProviderProfile;
+};
+/** A provider's profile; none for a provider that is not built in. */
+export declare const profileOf: (provider: string) => Option.Option<ProviderProfile>;
+/** A `"<provider>:<modelId>"` selection's model profile; none when it does not parse or its provider is not built in. */
+export declare const modelProfileOf: (selection: string) => Option.Option<ModelProfile>;

package/dist/llm/provider-profile.entity.functions.js

@@ -0,0 +1,83 @@
+import { Option, Schema } from "effect";
+import { parseModelSelection } from "@xandreed/core";
+import { BuiltInProvider } from "./provider-profile.entity.js";
+export const OPENCODE_CHAT_URL = "https://opencode.ai/zen/go/v1/chat/completions", OPENCODE_RESPONSES_API_URL = "https://opencode.ai/zen/v1", GOOGLE_CHAT_URL = "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions";
+const OPENCODE_RESPONSES_MODEL = /^gpt-/i, TEXT_ONLY_CODEX = new Set(["gpt-5.3-codex-spark"]), PUBLIC_EFFORTS = ["low", "medium", "high"], SUBSCRIPTION_EFFORTS = ["low", "medium", "high", "xhigh"], ALL_EFFORTS = ["none", "low", "medium", "high", "xhigh", "max"], ANTHROPIC = { _tag: "anthropic" }, OPENAI_CODEX = { _tag: "openai-codex" }, OPENAI_RESPONSES = { _tag: "openai-responses", apiUrl: Option.none(), strictJsonSchema: Option.none(), effort: "listed" }, OPENCODE_RESPONSES = { _tag: "openai-responses", apiUrl: Option.some(OPENCODE_RESPONSES_API_URL), strictJsonSchema: Option.some(!1), effort: "always" }, OPENCODE_CHAT = { _tag: "compat", moduleName: "OpenCode", chatUrl: OPENCODE_CHAT_URL, standardOnly: !1, usage: { reasoning: !0 } }, GOOGLE_CHAT = { _tag: "compat", moduleName: "Google", chatUrl: GOOGLE_CHAT_URL, standardOnly: !0, usage: { reasoning: !1 } }, bindsThinkingToPrefix = (id) => {
+  const version = /^claude-(fable|mythos|opus|sonnet|haiku)-(\d+)(?:-(\d{1,2}))?(?:-\d{8})?$/.exec(id);
+  if (version === null)
+    return !1;
+  const [, family, major, minor] = version;
+  return Number(major) * 100 + Number(minor ?? 0) >= (family === "fable" || family === "mythos" ? 501 : 505);
+}, NATIVE_EFFORTS = ["low", "medium", "high", "xhigh", "max"], advertised = (contextWindow, maxOutputTokens = 128000) => ({ contextWindow, maxOutputTokens }), adaptive = { _tag: "Adaptive", display: "summarized" }, off = { _tag: "Off" }, controls = (modes, defaultThinking, defaultEffort, forcedTools, reducedEfforts = Option.none()) => ({ source: "documented", modes, defaultThinking, defaultEffort, forcedTools, reducedEfforts }), knownAnthropic = {
+  "claude-fable-5": { images: !0, efforts: NATIVE_EFFORTS, bindsThinking: !1, limits: advertised(1e6), anthropic: controls(["Adaptive"], Option.some(adaptive), Option.some("high"), Option.some(!0)) },
+  "claude-fable-5-1": { images: !0, efforts: NATIVE_EFFORTS, bindsThinking: !0, limits: advertised(1e6), anthropic: controls(["Adaptive"], Option.some(adaptive), Option.some("high"), Option.some(!1)) },
+  "claude-mythos-5": { images: !0, efforts: NATIVE_EFFORTS, bindsThinking: !1, limits: advertised(1e6), anthropic: controls(["Adaptive"], Option.some(adaptive), Option.some("high"), Option.some(!0)) },
+  "claude-mythos-5-1": { images: !0, efforts: NATIVE_EFFORTS, bindsThinking: !0, limits: advertised(1e6), anthropic: controls(["Adaptive"], Option.some(adaptive), Option.some("high"), Option.some(!1)) },
+  "claude-opus-5-5": { images: !0, efforts: NATIVE_EFFORTS, bindsThinking: !0, limits: advertised(1e6), anthropic: controls(["Adaptive"], Option.some(adaptive), Option.some("medium"), Option.some(!1)) },
+  "claude-sonnet-5-5": { images: !0, efforts: NATIVE_EFFORTS, bindsThinking: !0, limits: advertised(1e6), anthropic: controls(["Adaptive", "BetweenTools"], Option.some(adaptive), Option.some("high"), Option.some(!1), Option.some(["low", "medium", "high"])) },
+  "claude-haiku-5-5": { images: !0, efforts: NATIVE_EFFORTS, bindsThinking: !0, limits: advertised(1e6), anthropic: controls(["Adaptive", "Off"], Option.some(adaptive), Option.some("medium"), Option.some(!0), Option.some(["low", "medium", "high"])) },
+  "claude-opus-5": { images: !0, efforts: NATIVE_EFFORTS, bindsThinking: !1, limits: { maxOutputTokens: 128000 }, anthropic: controls(["Adaptive", "Off"], Option.some(adaptive), Option.some("high"), Option.some(!0), Option.some(["low", "medium", "high"])) },
+  "claude-sonnet-5": { images: !0, efforts: NATIVE_EFFORTS, bindsThinking: !1, limits: advertised(1e6), anthropic: controls(["Adaptive", "Off"], Option.some(adaptive), Option.some("high"), Option.some(!0)) },
+  "claude-opus-4-8": { images: !0, efforts: NATIVE_EFFORTS, bindsThinking: !1, limits: advertised(1e6), anthropic: controls(["Adaptive", "Off"], Option.some(off), Option.some("high"), Option.some(!0)) },
+  "claude-opus-4-7": { images: !0, efforts: NATIVE_EFFORTS, bindsThinking: !1, limits: { maxOutputTokens: 128000 }, anthropic: controls(["Adaptive", "Off"], Option.some(off), Option.some("high"), Option.some(!0)) },
+  "claude-opus-4-6": { images: !0, efforts: ["low", "medium", "high", "max"], bindsThinking: !1, limits: advertised(1e6), anthropic: controls(["Adaptive", "Budget", "Off"], Option.some(off), Option.some("high"), Option.some(!0)) },
+  "claude-sonnet-4-6": { images: !0, efforts: ["low", "medium", "high", "max"], bindsThinking: !1, limits: { maxOutputTokens: 128000 }, anthropic: controls(["Adaptive", "Budget", "Off"], Option.some(off), Option.some("high"), Option.some(!0)) },
+  "claude-opus-4-5": { images: !0, efforts: ["low", "medium", "high"], bindsThinking: !1, limits: { maxOutputTokens: 64000 }, anthropic: controls(["Budget", "Off"], Option.some(off), Option.some("high"), Option.some(!0)) },
+  "claude-sonnet-4-5": { images: !0, efforts: [], bindsThinking: !1, limits: { maxOutputTokens: 64000 }, anthropic: controls(["Budget", "Off"], Option.some(off), Option.none(), Option.some(!0)) },
+  "claude-haiku-4-5": { images: !0, efforts: [], bindsThinking: !1, limits: advertised(200000, 64000), anthropic: controls(["Budget", "Off"], Option.some(off), Option.none(), Option.some(!0)) }
+};
+export const anthropicProfileOf = (modelId) => {
+  const base = modelId.replace(/-\d{8}$/, ""), known = Object.hasOwn(knownAnthropic, base) ? knownAnthropic[base] : void 0;
+  if (known !== void 0)
+    return { id: modelId, ...known };
+  if (/^claude-(?:fable|mythos)-5(?:-\d{1,2})?$/.test(base))
+    return {
+      id: modelId,
+      images: !0,
+      efforts: [],
+      bindsThinking: bindsThinkingToPrefix(modelId),
+      anthropic: {
+        source: "family-policy",
+        modes: ["Adaptive"],
+        defaultThinking: Option.some(adaptive),
+        defaultEffort: Option.none(),
+        forcedTools: Option.none(),
+        reducedEfforts: Option.none()
+      }
+    };
+  return { id: modelId, images: !0, efforts: [], bindsThinking: bindsThinkingToPrefix(modelId) };
+};
+const profile = (label, ids, traits, routeOf) => {
+  const modelOf = (id) => ({ id, ...traits(id) });
+  return { label, models: ids.map(modelOf), modelOf, routeOf };
+};
+export const PROVIDER_PROFILES = {
+  opencode: profile(Option.none(), [
+    "glm-5.2",
+    "glm-5.1",
+    "kimi-k2.7-code",
+    "kimi-k2.6",
+    "mimo-v2.5-pro",
+    "mimo-v2.5",
+    "qwen3.7-max",
+    "qwen3.7-plus",
+    "qwen3.6-plus",
+    "minimax-m3",
+    "minimax-m2.7",
+    "deepseek-v4-pro",
+    "deepseek-v4-flash"
+  ], (id) => ({ images: OPENCODE_RESPONSES_MODEL.test(id), efforts: [], bindsThinking: !1 }), (id) => OPENCODE_RESPONSES_MODEL.test(id) ? OPENCODE_RESPONSES : OPENCODE_CHAT),
+  "openai-codex": profile(Option.some("OpenAI subscription"), ["gpt-5.3-codex-spark", "gpt-5.4", "gpt-5.4-mini", "gpt-5.5", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra"], (id) => ({
+    images: !TEXT_ONLY_CODEX.has(id),
+    efforts: /^gpt-5\.6-(luna|sol|terra)$/.test(id) ? ALL_EFFORTS : /^gpt-5/.test(id) ? SUBSCRIPTION_EFFORTS : [],
+    bindsThinking: !1
+  }), () => OPENAI_CODEX),
+  openai: profile(Option.some("OpenAI API key"), ["gpt-5", "gpt-5.1", "gpt-5.2", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.5", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra"], (id) => ({ images: !0, efforts: /^gpt-5/.test(id) ? PUBLIC_EFFORTS : [], bindsThinking: !1 }), () => OPENAI_RESPONSES),
+  anthropic: profile(Option.none(), ["claude-fable-5", "claude-haiku-4-5", "claude-opus-4-8", "claude-sonnet-5", "claude-fable-5-1", "claude-opus-5-5", "claude-sonnet-5-5", "claude-haiku-5-5"], (id) => {
+    const { id: _id, ...traits } = anthropicProfileOf(id);
+    return traits;
+  }, () => ANTHROPIC),
+  google: profile(Option.none(), ["gemini-3-flash", "gemini-3.1-pro", "gemini-3.5-flash"], () => ({ images: !0, efforts: [], bindsThinking: !1 }), () => GOOGLE_CHAT)
+};
+const isBuiltIn = Schema.is(BuiltInProvider);
+export const profileOf = (provider) => isBuiltIn(provider) ? Option.some(PROVIDER_PROFILES[provider]) : Option.none(), modelProfileOf = (selection) => Option.flatMap(parseModelSelection(selection), ({ provider, modelId }) => Option.map(profileOf(provider), (found) => found.modelOf(modelId)));

package/dist/llm/provider-profile.entity.js

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+import { AnthropicEffort, ModelThinking } from "./model-settings.entity.js";
+export const AnthropicModelTraits = Schema.Struct({
+  source: Schema.Literals(["documented", "family-policy"]),
+  modes: Schema.Array(Schema.Literals(ModelThinking.discriminants)),
+  defaultThinking: Schema.OptionFromNullOr(ModelThinking),
+  defaultEffort: Schema.OptionFromNullOr(AnthropicEffort),
+  forcedTools: Schema.OptionFromNullOr(Schema.Boolean),
+  reducedEfforts: Schema.OptionFromNullOr(Schema.Array(AnthropicEffort))
+}), BuiltInProvider = Schema.Literals(["opencode", "openai-codex", "openai", "anthropic", "google"]);