@xandreed/plugin-models 0.13.0 → 0.15.0

package/dist/llm/model-retry-policy.entity.functions.js

@@ -0,0 +1,33 @@
+import { Option } from "effect";
+import { ModelRequestState } from "./model-retry-policy.entity.js";
+const DECIMAL = /^(?:\d+(?:\.\d*)?|\.\d+)$/;
+export const retryAfterMillis = (value, now) => {
+  const text = value.trim();
+  if (DECIMAL.test(text)) {
+    const millis = Number(text) * 1000;
+    return Number.isFinite(millis) ? Option.some(millis) : Option.none();
+  }
+  const date = /^[A-Za-z]{3,9}[ ,]/.test(text) ? Date.parse(text) : NaN;
+  return Number.isFinite(date) ? Option.some(Math.max(0, date - now)) : Option.none();
+}, retryAfterMsMillis = (value) => {
+  const text = value.trim(), millis = DECIMAL.test(text) ? Number(text) : NaN;
+  return Number.isFinite(millis) ? Option.some(millis) : Option.none();
+};
+const headerText = (headers, name) => Option.filter(Option.fromNullishOr(Object.hasOwn(headers, name) ? headers[name] : void 0), (value) => typeof value === "string");
+export const retryHintMillis = (headers, now) => Option.orElse(Option.flatMap(headerText(headers, "retry-after-ms"), retryAfterMsMillis), () => Option.flatMap(headerText(headers, "retry-after"), (value) => retryAfterMillis(value, now))), retryDelayMillis = (policy, attempt, unit, hint) => {
+  const base = Math.min(policy.backoff.maxMs, policy.backoff.initialMs * 2 ** Math.min(1023, Math.max(0, attempt - 1))), jittered = Math.min(policy.backoff.maxMs, Math.max(0, Math.round(base * (1 - policy.backoff.jitter + 2 * policy.backoff.jitter * unit))));
+  return Math.max(jittered, Math.min(policy.retryAfterMaxMs, Option.getOrElse(hint, () => 0)));
+}, primaryAttemptLimit = (policy, reserveFallback) => reserveFallback && policy.maxAttempts >= 2 ? policy.maxAttempts - 1 : policy.maxAttempts, retryableModelFailure = (kind) => kind === "Transient" || kind === "Timeout" || kind === "RateLimit", startAttemptState = (state, policy, reserveFallback) => {
+  const start = () => state.attempts < (state.rung === "Primary" ? primaryAttemptLimit(policy, reserveFallback) : policy.maxAttempts) ? Option.some({ _tag: "Sending", rung: state.rung, attempts: state.attempts + 1 }) : Option.none();
+  return ModelRequestState.match(state, {
+    Ready: start,
+    Sending: () => Option.none(),
+    Rejected: (value) => retryableModelFailure(value.kind) && value.replayable ? start() : Option.none(),
+    Committed: () => Option.none()
+  });
+}, enterFallbackState = (state, policy, reserveFallback) => ModelRequestState.match(state, {
+  Ready: () => Option.none(),
+  Sending: () => Option.none(),
+  Committed: () => Option.none(),
+  Rejected: (value) => reserveFallback && policy.maxAttempts >= 2 && value.rung === "Primary" && value.attempts >= primaryAttemptLimit(policy, !0) && value.attempts < policy.maxAttempts && value.replayable && retryableModelFailure(value.kind) ? Option.some({ _tag: "Ready", rung: "Fallback", attempts: value.attempts }) : Option.none()
+});

package/dist/llm/model-retry-policy.entity.js

@@ -0,0 +1,23 @@
+import { Schema } from "effect";
+import { ModelFailureKind } from "@xandreed/core";
+const positive = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)), nonnegative = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+export const ModelRetryPolicy = Schema.Struct({
+  maxAttempts: positive,
+  requestTimeoutMs: positive,
+  bodyIdleTimeoutMs: positive,
+  totalTimeoutMs: positive,
+  retryAfterMaxMs: nonnegative,
+  backoff: Schema.Struct({ initialMs: nonnegative, maxMs: nonnegative, jitter: Schema.Number.check(Schema.isBetween({ minimum: 0, maximum: 1 })) }).check(Schema.makeFilter((value) => value.maxMs >= value.initialMs ? !0 : "maximum backoff must be at least its initial delay"))
+}), modelRetryDefaults = {
+  maxAttempts: 4,
+  requestTimeoutMs: 300000,
+  bodyIdleTimeoutMs: 300000,
+  totalTimeoutMs: 600000,
+  retryAfterMaxMs: 60000,
+  backoff: { initialMs: 1000, maxMs: 4000, jitter: 0.2 }
+}, ModelRequestRung = Schema.Literals(["Primary", "Fallback"]), ModelRequestState = Schema.Union([
+  Schema.TaggedStruct("Ready", { rung: ModelRequestRung, attempts: nonnegative }),
+  Schema.TaggedStruct("Sending", { rung: ModelRequestRung, attempts: positive }),
+  Schema.TaggedStruct("Rejected", { rung: ModelRequestRung, attempts: positive, kind: ModelFailureKind, replayable: Schema.Boolean, retryAt: Schema.optionalKey(nonnegative) }),
+  Schema.TaggedStruct("Committed", { rung: ModelRequestRung, attempts: positive })
+]).pipe(Schema.toTaggedUnion("_tag"));

package/dist/llm/model-settings.entity.d.ts

@@ -0,0 +1,85 @@
+import { Schema } from "effect";
+/** The public reasoning summary returned with adaptive or manual thinking. @public */
+export declare const ThinkingDisplay: Schema.Literals<readonly ["summarized", "omitted"]>;
+export type ThinkingDisplay = typeof ThinkingDisplay.Type;
+/** Model-specific thinking controls; modes carry only their supported companions. @public */
+export declare const ModelThinking: 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", {}>]>;
+export type ModelThinking = typeof ModelThinking.Type;
+/** Static host settings for one full provider:model selection. @public */
+export declare const ModelSettings: Schema.Struct<{
+    readonly thinking: Schema.optionalKey<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 effort: Schema.optionalKey<Schema.Literals<readonly ["none", "low", "medium", "high", "xhigh", "max"]>>;
+    readonly limits: Schema.optionalKey<Schema.Struct<{
+        readonly contextWindow: Schema.optionalKey<Schema.Int>;
+        readonly maxOutputTokens: Schema.optionalKey<Schema.Int>;
+    }>>;
+    readonly promptCache: Schema.optionalKey<Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Auto", {
+        readonly ttl: Schema.Literals<readonly ["5m", "1h"]>;
+    }>, Schema.TaggedStruct<"TopLevel", {
+        readonly ttl: Schema.Literals<readonly ["5m", "1h"]>;
+    }>, Schema.TaggedStruct<"Off", {}>]>>;
+}>;
+export type ModelSettings = typeof ModelSettings.Type;
+/** Settings keyed by the complete provider:modelId selection, including gateway aliases. @public */
+export declare const ModelSettingsMap: Schema.$Record<Schema.String, Schema.Struct<{
+    readonly thinking: Schema.optionalKey<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 effort: Schema.optionalKey<Schema.Literals<readonly ["none", "low", "medium", "high", "xhigh", "max"]>>;
+    readonly limits: Schema.optionalKey<Schema.Struct<{
+        readonly contextWindow: Schema.optionalKey<Schema.Int>;
+        readonly maxOutputTokens: Schema.optionalKey<Schema.Int>;
+    }>>;
+    readonly promptCache: Schema.optionalKey<Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Auto", {
+        readonly ttl: Schema.Literals<readonly ["5m", "1h"]>;
+    }>, Schema.TaggedStruct<"TopLevel", {
+        readonly ttl: Schema.Literals<readonly ["5m", "1h"]>;
+    }>, Schema.TaggedStruct<"Off", {}>]>>;
+}>>;
+export type ModelSettingsMap = typeof ModelSettingsMap.Type;
+declare const ModelSettingsError_base: Schema.Class<ModelSettingsError, Schema.TaggedStruct<"ModelSettingsError", {
+    readonly reason: Schema.Literals<readonly ["Settings", "Selection", "OutputLimit", "Thinking", "Effort", "Budget", "ToolChoice", "Binding"]>;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** Why configured model controls cannot form a valid Messages request. @public */
+export declare class ModelSettingsError extends ModelSettingsError_base {
+}
+/** Anthropic's native vocabulary; neutral none is mapped to low by local adapter policy. */
+export declare const AnthropicEffort: Schema.Literals<readonly ["low", "medium", "high", "xhigh", "max"]>;
+export type AnthropicEffort = typeof AnthropicEffort.Type;
+/** Effective public request settings; unknown thinking/effort remains absent. */
+export declare const ResolvedAnthropicSettings: Schema.Struct<{
+    readonly selection: Schema.String;
+    readonly thinking: 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 effort: Schema.OptionFromNullOr<Schema.Literals<readonly ["low", "medium", "high", "xhigh", "max"]>>;
+    readonly maxOutputTokens: Schema.Int;
+    readonly promptCache: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Auto", {
+        readonly ttl: Schema.Literals<readonly ["5m", "1h"]>;
+    }>, Schema.TaggedStruct<"TopLevel", {
+        readonly ttl: Schema.Literals<readonly ["5m", "1h"]>;
+    }>, Schema.TaggedStruct<"Off", {}>]>;
+    readonly limits: Schema.optionalKey<Schema.Struct<{
+        readonly contextWindow: Schema.optionalKey<Schema.Int>;
+        readonly maxOutputTokens: Schema.optionalKey<Schema.Int>;
+    }>>;
+}>;
+export type ResolvedAnthropicSettings = typeof ResolvedAnthropicSettings.Type;
+export {};

package/dist/llm/model-settings.entity.functions.d.ts

@@ -0,0 +1,11 @@
+import { Option, Result } from "effect";
+import type { ModelCallPolicy } from "@xandreed/core";
+import { ModelSettingsError } from "./model-settings.entity.js";
+import type { ModelSettingsMap, ResolvedAnthropicSettings } from "./model-settings.entity.js";
+/** Resolve public settings without wire fields; an unknown model requires an explicit output cap. */
+export declare const resolveAnthropicSettings: (selection: string, settings: ModelSettingsMap, policy: Option.Option<ModelCallPolicy>) => Result.Result<ResolvedAnthropicSettings, ModelSettingsError>;
+/** Validate request-dependent controls after resolution, before any network I/O. */
+export declare const validateAnthropicRequest: (settings: ResolvedAnthropicSettings, request: {
+    readonly forcedTool: boolean;
+    readonly binding: boolean;
+}) => Result.Result<void, ModelSettingsError>;

package/dist/llm/model-settings.entity.functions.js

@@ -0,0 +1,49 @@
+import { Array as Arr, Option, Result, Schema } from "effect";
+import { parseModelSelection } from "@xandreed/core";
+import { anthropicProfileOf } from "./provider-profile.entity.functions.js";
+import { AnthropicEffort, ModelSettings, ModelSettingsError, ModelThinking } from "./model-settings.entity.js";
+const error = (reason, message) => new ModelSettingsError({ reason, message }), outputLimit = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)), EFFORT_ORDER = ["low", "medium", "high", "xhigh", "max"], nativeEffort = (value) => value === "none" ? "low" : value, nearestEffort = (requested, supported) => Option.orElse(Arr.findLast(supported, (level) => EFFORT_ORDER.indexOf(level) <= EFFORT_ORDER.indexOf(requested)), () => Arr.head(supported)), displayed = (thinking) => ModelThinking.match(thinking, {
+  Adaptive: (value) => ({ ...value, display: value.display ?? "summarized" }),
+  Budget: (value) => ({ ...value, display: value.display ?? "summarized" }),
+  BetweenTools: (value) => value,
+  Off: (value) => value
+});
+export const resolveAnthropicSettings = (selection, settings, policy) => {
+  const parsed = parseModelSelection(selection);
+  if (Option.isNone(parsed))
+    return Result.fail(error("Selection", "the model selection must name a provider and model"));
+  const decoded = Schema.decodeUnknownResult(ModelSettings)(Object.hasOwn(settings, selection) ? settings[selection] : {}, { onExcessProperty: "error" });
+  if (Result.isFailure(decoded))
+    return Result.fail(error("Settings", "the per-model settings do not decode; check thinking companions, effort and positive integer limits"));
+  const configured = decoded.success, profile = anthropicProfileOf(parsed.value.modelId), traits = profile.anthropic, limits = { ...profile.limits, ...configured.limits }, maximum = Option.orElse(Option.flatMap(policy, (value) => Option.fromNullishOr(value.maxOutputTokens)), () => Option.fromNullishOr(limits.maxOutputTokens));
+  if (Option.isNone(maximum))
+    return Result.fail(error("OutputLimit", "an unknown Messages model needs maxOutputTokens in its call policy or per-model limits"));
+  const output = Schema.decodeUnknownResult(outputLimit)(maximum.value);
+  if (Result.isFailure(output))
+    return Result.fail(error("OutputLimit", "maxOutputTokens must be a positive finite integer"));
+  const thinking = Option.map(Option.orElse(Option.fromNullishOr(configured.thinking), () => traits?.defaultThinking ?? Option.none()), displayed);
+  if (Option.exists(thinking, (value) => traits !== void 0 && !traits.modes.includes(value._tag)))
+    return Result.fail(error("Thinking", "the configured thinking mode is not supported by this Messages model"));
+  const noEffort = traits?.source === "documented" && profile.efforts.length === 0;
+  if (noEffort && configured.effort !== void 0)
+    return Result.fail(error("Effort", "this Messages model does not support per-model effort"));
+  const reduced = Option.exists(thinking, (value) => value._tag === "Off" || value._tag === "BetweenTools") ? traits?.reducedEfforts ?? Option.none() : Option.none(), supported = traits?.source === "documented" ? Option.some(EFFORT_ORDER.filter((level) => profile.efforts.includes(level) && Option.match(reduced, { onNone: () => !0, onSome: (allowed) => allowed.includes(level) }))) : Option.none(), explicit = Option.map(Option.fromNullishOr(configured.effort), nativeEffort);
+  if (Option.exists(explicit, (level) => traits?.source === "documented" && !profile.efforts.includes(level)))
+    return Result.fail(error("Effort", "the configured effort is not supported by this Messages model"));
+  if (Option.exists(explicit, (level) => Option.exists(reduced, (allowed) => !allowed.includes(level))))
+    return Result.fail(error("Effort", "this reduced-thinking mode requires low, medium or high effort"));
+  const ambient = Option.map(Option.map(policy, (value) => value.effort), nativeEffort), effort = noEffort ? Option.none() : Option.orElse(Option.flatMap(ambient, (level) => Option.match(supported, { onNone: () => Option.some(level), onSome: (levels) => nearestEffort(level, levels) })), () => Option.orElse(explicit, () => traits?.defaultEffort ?? Option.none()));
+  if (Option.exists(thinking, (value) => value._tag === "Budget" && value.budgetTokens >= output.success))
+    return Result.fail(error("Budget", "the thinking budget must be less than maxOutputTokens"));
+  return Result.succeed({ selection, thinking, effort, maxOutputTokens: output.success, promptCache: configured.promptCache ?? { _tag: "Auto", ttl: "5m" }, ...Object.keys(limits).length === 0 ? {} : { limits } });
+}, validateAnthropicRequest = (settings, request) => {
+  const parsed = parseModelSelection(settings.selection);
+  if (Option.isNone(parsed))
+    return Result.fail(error("Selection", "the model selection must name a provider and model"));
+  const profile = anthropicProfileOf(parsed.value.modelId);
+  if (request.forcedTool && (Option.contains(profile.anthropic?.forcedTools ?? Option.none(), !1) || Option.exists(settings.thinking, (value) => value._tag === "Budget")))
+    return Result.fail(error("ToolChoice", "this Messages model and thinking mode do not support forced tool choice"));
+  if (request.binding && (!profile.bindsThinking || !Option.exists(settings.thinking, (value) => value._tag === "Adaptive")))
+    return Result.fail(error("Binding", "thinking binding requires a supported Messages model with adaptive thinking"));
+  return Result.succeed(void 0);
+};

package/dist/llm/model-settings.entity.js

@@ -0,0 +1,28 @@
+import { Option, Schema } from "effect";
+import { ModelLimits, ReasoningEffort, parseModelSelection } from "@xandreed/core";
+import { PromptCacheSettings } from "./prompt-cache.entity.js";
+export const ThinkingDisplay = Schema.Literals(["summarized", "omitted"]), ModelThinking = Schema.Union([
+  Schema.TaggedStruct("Adaptive", { display: Schema.optionalKey(ThinkingDisplay) }),
+  Schema.TaggedStruct("Budget", { budgetTokens: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1024)), display: Schema.optionalKey(ThinkingDisplay) }),
+  Schema.TaggedStruct("BetweenTools", {}),
+  Schema.TaggedStruct("Off", {})
+]).pipe(Schema.toTaggedUnion("_tag")), ModelSettings = Schema.Struct({
+  thinking: Schema.optionalKey(ModelThinking),
+  effort: Schema.optionalKey(ReasoningEffort),
+  limits: Schema.optionalKey(ModelLimits),
+  promptCache: Schema.optionalKey(PromptCacheSettings)
+}), ModelSettingsMap = Schema.Record(Schema.String, ModelSettings).check(Schema.makeFilter((settings) => Object.keys(settings).every((selection) => Option.isSome(parseModelSelection(selection))) ? !0 : "keys must be full provider:modelId selections"));
+
+export class ModelSettingsError extends Schema.TaggedError()("ModelSettingsError", {
+  reason: Schema.Literals(["Settings", "Selection", "OutputLimit", "Thinking", "Effort", "Budget", "ToolChoice", "Binding"]),
+  message: Schema.String
+}) {
+}
+export const AnthropicEffort = ReasoningEffort.pick(["low", "medium", "high", "xhigh", "max"]), ResolvedAnthropicSettings = Schema.Struct({
+  selection: Schema.String,
+  thinking: Schema.OptionFromNullOr(ModelThinking),
+  effort: Schema.OptionFromNullOr(AnthropicEffort),
+  maxOutputTokens: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)),
+  promptCache: PromptCacheSettings,
+  limits: Schema.optionalKey(ModelLimits)
+});

package/dist/llm/model-usage.entity.d.ts

@@ -0,0 +1,61 @@
+import { Schema } from "effect";
+/** Reported cumulative counts; an absent field is not a reported zero. */
+export declare const ProviderUsageCounts: Schema.Struct<{
+    readonly inputTokens: Schema.optionalKey<Schema.Int>;
+    readonly outputTokens: Schema.optionalKey<Schema.Int>;
+    readonly cacheReadTokens: Schema.optionalKey<Schema.Int>;
+    readonly cacheWriteTokens: Schema.optionalKey<Schema.Int>;
+    readonly reasoningTokens: Schema.optionalKey<Schema.Int>;
+}>;
+export type ProviderUsageCounts = typeof ProviderUsageCounts.Type;
+export declare const ProviderUsageObservation: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Collecting", {
+    readonly counts: Schema.Struct<{
+        readonly inputTokens: Schema.optionalKey<Schema.Int>;
+        readonly outputTokens: Schema.optionalKey<Schema.Int>;
+        readonly cacheReadTokens: Schema.optionalKey<Schema.Int>;
+        readonly cacheWriteTokens: Schema.optionalKey<Schema.Int>;
+        readonly reasoningTokens: Schema.optionalKey<Schema.Int>;
+    }>;
+}>, Schema.TaggedStruct<"Final", {
+    readonly counts: Schema.Struct<{
+        readonly inputTokens: Schema.optionalKey<Schema.Int>;
+        readonly outputTokens: Schema.optionalKey<Schema.Int>;
+        readonly cacheReadTokens: Schema.optionalKey<Schema.Int>;
+        readonly cacheWriteTokens: Schema.optionalKey<Schema.Int>;
+        readonly reasoningTokens: Schema.optionalKey<Schema.Int>;
+    }>;
+}>]>;
+export type ProviderUsageObservation = typeof ProviderUsageObservation.Type;
+export declare const noProviderUsage: ProviderUsageObservation;
+export declare const AnthropicUsageCounts: Schema.Struct<{
+    readonly input_tokens: Schema.optionalKey<Schema.NullOr<Schema.Int>>;
+    readonly output_tokens: Schema.optionalKey<Schema.NullOr<Schema.Int>>;
+    readonly cache_read_input_tokens: Schema.optionalKey<Schema.NullOr<Schema.Int>>;
+    readonly cache_creation_input_tokens: Schema.optionalKey<Schema.NullOr<Schema.Int>>;
+}>;
+export declare const OpenAiUsageCounts: Schema.Struct<{
+    readonly input_tokens: Schema.optionalKey<Schema.NullOr<Schema.Int>>;
+    readonly prompt_tokens: Schema.optionalKey<Schema.NullOr<Schema.Int>>;
+    readonly output_tokens: Schema.optionalKey<Schema.NullOr<Schema.Int>>;
+    readonly completion_tokens: Schema.optionalKey<Schema.NullOr<Schema.Int>>;
+    readonly prompt_cache_hit_tokens: Schema.optionalKey<Schema.NullOr<Schema.Int>>;
+    readonly cached_tokens: Schema.optionalKey<Schema.NullOr<Schema.Int>>;
+    readonly input_tokens_details: Schema.optionalKey<Schema.NullOr<Schema.Struct<{
+        readonly cached_tokens: Schema.optionalKey<Schema.NullOr<Schema.Int>>;
+        readonly cache_write_tokens: Schema.optionalKey<Schema.NullOr<Schema.Int>>;
+    }>>>;
+    readonly prompt_tokens_details: Schema.optionalKey<Schema.NullOr<Schema.Struct<{
+        readonly cached_tokens: Schema.optionalKey<Schema.NullOr<Schema.Int>>;
+        readonly cache_write_tokens: Schema.optionalKey<Schema.NullOr<Schema.Int>>;
+    }>>>;
+    readonly output_tokens_details: Schema.optionalKey<Schema.NullOr<Schema.Struct<{
+        readonly reasoning_tokens: Schema.optionalKey<Schema.NullOr<Schema.Int>>;
+    }>>>;
+    readonly completion_tokens_details: Schema.optionalKey<Schema.NullOr<Schema.Struct<{
+        readonly reasoning_tokens: Schema.optionalKey<Schema.NullOr<Schema.Int>>;
+    }>>>;
+}>;
+/** The usage envelope is observed before downstream completion/schema acceptance. */
+export declare const ProviderUsageBody: Schema.Struct<{
+    readonly usage: Schema.optionalKey<Schema.Unknown>;
+}>;

package/dist/llm/model-usage.entity.functions.d.ts

@@ -0,0 +1,11 @@
+import { Option } from "effect";
+import type { ModelCallUsage } from "@xandreed/core";
+import type { ProviderFailureProtocol } from "./provider-failure.entity.js";
+import { ProviderUsageCounts } from "./model-usage.entity.js";
+import type { ProviderUsageObservation } from "./model-usage.entity.js";
+/** Read only the supported provider's token counters before absent fields get SDK defaults. */
+export declare const providerUsageCounts: (protocol: ProviderFailureProtocol, value: unknown, reasoning?: boolean) => Option.Option<ProviderUsageCounts>;
+/** Reported cumulative fields replace their earlier values; null/absent fields never erase facts. */
+export declare const observeProviderUsage: (before: ProviderUsageObservation, counts: ProviderUsageCounts, final: boolean) => ProviderUsageObservation;
+/** Normalize the observed subtotal while preserving coverage and finality separately. */
+export declare const modelCallUsageOf: (protocol: ProviderFailureProtocol, observation: ProviderUsageObservation) => ModelCallUsage;

package/dist/llm/model-usage.entity.functions.js

@@ -0,0 +1,24 @@
+import { Option, Schema } from "effect";
+import { tokenUsage } from "@xandreed/core";
+import { AnthropicUsageCounts, OpenAiUsageCounts, ProviderUsageCounts } from "./model-usage.entity.js";
+const present = (key, value) => value == null ? {} : { [key]: value };
+export const providerUsageCounts = (protocol, value, reasoning = !0) => protocol === "anthropic" ? Option.map(Schema.decodeUnknownOption(AnthropicUsageCounts)(value), (usage) => ({
+  ...present("inputTokens", usage.input_tokens),
+  ...present("outputTokens", usage.output_tokens),
+  ...present("cacheReadTokens", usage.cache_read_input_tokens),
+  ...present("cacheWriteTokens", usage.cache_creation_input_tokens)
+})) : Option.map(Schema.decodeUnknownOption(OpenAiUsageCounts)(value), (usage) => ({
+  ...present("inputTokens", usage.input_tokens ?? usage.prompt_tokens),
+  ...present("outputTokens", usage.output_tokens ?? usage.completion_tokens),
+  ...present("cacheReadTokens", usage.prompt_cache_hit_tokens ?? usage.cached_tokens ?? usage.prompt_tokens_details?.cached_tokens ?? usage.input_tokens_details?.cached_tokens),
+  ...present("cacheWriteTokens", usage.prompt_tokens_details?.cache_write_tokens ?? usage.input_tokens_details?.cache_write_tokens),
+  ...reasoning ? present("reasoningTokens", usage.output_tokens_details?.reasoning_tokens ?? usage.completion_tokens_details?.reasoning_tokens) : {}
+})), observeProviderUsage = (before, counts, final) => ({ _tag: final && counts.outputTokens !== void 0 ? "Final" : before._tag, counts: { ...before.counts, ...counts } }), modelCallUsageOf = (protocol, observation) => {
+  const counts = observation.counts, reported = Object.keys(ProviderUsageCounts.fields).filter((key) => counts[key] !== void 0);
+  if (reported.length === 0)
+    return { _tag: "Unknown" };
+  const inputTokens = (counts.inputTokens ?? 0) + (protocol === "anthropic" ? (counts.cacheReadTokens ?? 0) + (counts.cacheWriteTokens ?? 0) : 0), usage = tokenUsage({ ...counts, inputTokens, outputTokens: counts.outputTokens ?? 0 });
+  if (Object.values(usage).some((count) => !Number.isSafeInteger(count)))
+    return { _tag: "Unknown" };
+  return observation._tag === "Final" && counts.inputTokens !== void 0 && counts.outputTokens !== void 0 ? { _tag: "Known", usage } : { _tag: "Partial", usage, reported };
+};

package/dist/llm/model-usage.entity.js

@@ -0,0 +1,19 @@
+import { Schema } from "effect";
+const count = Schema.optionalKey(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)));
+export const ProviderUsageCounts = Schema.Struct({ inputTokens: count, outputTokens: count, cacheReadTokens: count, cacheWriteTokens: count, reasoningTokens: count }), ProviderUsageObservation = Schema.Union([
+  Schema.TaggedStruct("Collecting", { counts: ProviderUsageCounts }),
+  Schema.TaggedStruct("Final", { counts: ProviderUsageCounts })
+]).pipe(Schema.toTaggedUnion("_tag")), noProviderUsage = { _tag: "Collecting", counts: {} };
+const wireCount = Schema.optionalKey(Schema.NullOr(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))));
+export const AnthropicUsageCounts = Schema.Struct({ input_tokens: wireCount, output_tokens: wireCount, cache_read_input_tokens: wireCount, cache_creation_input_tokens: wireCount }), OpenAiUsageCounts = Schema.Struct({
+  input_tokens: wireCount,
+  prompt_tokens: wireCount,
+  output_tokens: wireCount,
+  completion_tokens: wireCount,
+  prompt_cache_hit_tokens: wireCount,
+  cached_tokens: wireCount,
+  input_tokens_details: Schema.optionalKey(Schema.NullOr(Schema.Struct({ cached_tokens: wireCount, cache_write_tokens: wireCount }))),
+  prompt_tokens_details: Schema.optionalKey(Schema.NullOr(Schema.Struct({ cached_tokens: wireCount, cache_write_tokens: wireCount }))),
+  output_tokens_details: Schema.optionalKey(Schema.NullOr(Schema.Struct({ reasoning_tokens: wireCount }))),
+  completion_tokens_details: Schema.optionalKey(Schema.NullOr(Schema.Struct({ reasoning_tokens: wireCount })))
+}), ProviderUsageBody = Schema.Struct({ usage: Schema.optionalKey(Schema.Unknown) });

package/dist/llm/modelCatalog.d.ts

@@ -1,10 +1,50 @@
 import { Layer } from "effect";
-import { AuthStore, ModelCatalog } from "@xandreed/core";
-import type { Credential, ModelCatalogEntryType } from "@xandreed/core";
-export declare const configuredModelCatalog: (credentials: ReadonlyMap<string, Credential>) => ReadonlyArray<ModelCatalogEntryType>;
-export type ReasoningEffort = "none" | "low" | "medium" | "high" | "xhigh" | "max";
-/** The reasoning controls accepted by each routed model. `none` on the
- * gpt-5.6 subscription dialect is live-probed (2026-07-16: accepted,
- * reasoning_tokens 0; `minimal` rejected). */
+import { ModelCatalog } from "@xandreed/core";
+import { AuthStore } from "../ports/auth-store.port.js";
+import type { ModelCatalogEntryType, ReasoningEffortType } from "@xandreed/core";
+import type { Credential } from "../ports/auth-store.port.js";
+import type { ModelEndpoints } from "../ports/model-endpoints.port.js";
+import type { ModelSettingsMap } from "./model-settings.entity.js";
+/** OpenCode serves its GPT models through the OpenAI Responses protocol, the others through chat completions. */
+export declare const usesOpenCodeResponses: (modelId: string) => boolean;
+/**
+ * Whether a built-in route sends a model images: Anthropic's Messages API,
+ * the OpenAI Responses routes (`openai`, `openai-codex` but its text-only
+ * Spark model, OpenCode's `gpt-*`) and Gemini's chat completions do;
+ * OpenCode's other models are text-only until each is verified. A
+ * configured endpoint says so itself (`ModelEndpoint.images`). Where it is
+ * false, a request's images are sent as label lines.
+ *
+ * @public
+ */
+export declare const imageInputFor: (selection: string) => boolean;
+/**
+ * The models of every provider with a credential. Each entry's `input` is
+ * what its route reads, as `buildProvider` routes it: `endpoints` (the
+ * models plugin's configured ones; none by default) replace a built-in
+ * route of their name.
+ */
+export declare const configuredModelCatalog: (credentials: ReadonlyMap<string, Credential>, endpoints?: ModelEndpoints, settings?: ModelSettingsMap) => ReadonlyArray<ModelCatalogEntryType>;
+/** @public */
+export type ReasoningEffort = ReasoningEffortType;
+/**
+ * A built-in model profile's reasoning controls. Configured route overrides are not inferred here.
+ *
+ * @public
+ */
 export declare const reasoningEffortsFor: (selection: string) => ReadonlyArray<ReasoningEffort>;
+/** The efforts of the public OpenAI API's vocabulary, which the OpenAI Responses routes and the chat-completions gateways take. */
+export type PublicReasoningEffort = "low" | "medium" | "high";
+/**
+ * An effort in the public vocabulary: `xhigh` and `max` are `high`, `none`
+ * is `low`, the others themselves. Only the subscription dialect takes the
+ * whole vocabulary (and only it is probe-verified for `none`). Anthropic
+ * Messages uses its own native effort resolution instead of this clamp.
+ */
+export declare const publicReasoningEffort: (effort: ReasoningEffort) => PublicReasoningEffort;
+/**
+ * The catalog over the AuthStore's credentials and the configured endpoints (`CurrentModelEndpoints`).
+ *
+ * @public
+ */
 export declare const ConfiguredModelCatalogLive: Layer.Layer<ModelCatalog, never, AuthStore>;

package/dist/llm/modelCatalog.js

@@ -1,58 +1,32 @@
-import { Effect, Layer } from "effect";
-import { AuthStore, ModelCatalog } from "@xandreed/core";
-const OPENCODE_MODELS = [
-  "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"
-], MODELS = {
-  opencode: OPENCODE_MODELS,
-  "openai-codex": [
-    "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"
-  ],
-  openai: [
-    "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"
-  ],
-  anthropic: ["claude-fable-5", "claude-haiku-4-5", "claude-opus-4-8", "claude-sonnet-5"],
-  google: ["gemini-3-flash", "gemini-3.1-pro", "gemini-3.5-flash"]
+import { Effect, Layer, Option } from "effect";
+import { ModelCatalog } from "@xandreed/core";
+import { AuthStore } from "../ports/auth-store.port.js";
+import { CurrentModelEndpoints } from "../ports/model-endpoints.port.js";
+import { CurrentModelSettings } from "../ports/model-settings.port.js";
+import { anthropicProfileOf, modelProfileOf, profileOf, PROVIDER_PROFILES } from "./provider-profile.entity.functions.js";
+export const usesOpenCodeResponses = (modelId) => PROVIDER_PROFILES.opencode.routeOf(modelId)._tag === "openai-responses", imageInputFor = (selection) => Option.exists(modelProfileOf(selection), (model) => model.images);
+const routeReadsImages = (provider, model, credential, endpoints) => Option.match(Object.hasOwn(endpoints, provider) ? Option.fromNullishOr(endpoints[provider]) : Option.none(), {
+  onSome: (endpoint) => endpoint.images ?? (endpoint.api === "anthropic-messages" ? anthropicProfileOf(model.id).images : !1),
+  onNone: () => !(credential.type === "local" && credential.baseUrl !== void 0) && model.images
+}), routeLimits = (provider, model, credential, endpoints, settings) => {
+  if (!Option.match(Object.hasOwn(endpoints, provider) ? Option.fromNullishOr(endpoints[provider]) : Option.none(), {
+    onSome: (endpoint) => endpoint.api === "anthropic-messages",
+    onNone: () => !(credential.type === "local" && credential.baseUrl !== void 0) && Option.exists(profileOf(provider), (profile) => profile.routeOf(model.id)._tag === "anthropic")
+  }))
+    return Option.none();
+  const selection = `${provider}:${model.id}`, configured = Object.hasOwn(settings, selection) ? settings[selection]?.limits : void 0, limits = { ...anthropicProfileOf(model.id).limits, ...configured };
+  return Object.keys(limits).length === 0 ? Option.none() : Option.some(limits);
 };
-export const configuredModelCatalog = (credentials) => [...credentials].flatMap(([provider, credential]) => (MODELS[provider] ?? []).map((model) => ({
-  selection: `${provider}:${model}`,
-  label: provider === "openai-codex" ? `OpenAI subscription \xB7 ${model}` : provider === "openai" ? `OpenAI API key \xB7 ${model}` : void 0,
-  provider,
-  credential: credential.type
-}))), reasoningEffortsFor = (selection) => {
-  if (/^openai-codex:gpt-5\.6-(luna|sol|terra)$/.test(selection))
-    return ["none", "low", "medium", "high", "xhigh", "max"];
-  if (/^openai-codex:gpt-5/.test(selection))
-    return ["low", "medium", "high", "xhigh"];
-  if (/^openai:gpt-5/.test(selection))
-    return ["low", "medium", "high"];
-  return [];
-}, ConfiguredModelCatalogLive = Layer.effect(ModelCatalog, Effect.map(AuthStore, (auth) => ({
-  list: auth.all.pipe(Effect.orElseSucceed(() => new Map), Effect.map(configuredModelCatalog))
-})));
+export const configuredModelCatalog = (credentials, endpoints = {}, settings = {}) => [...credentials].flatMap(([provider, credential]) => Option.match(profileOf(provider), {
+  onNone: () => [],
+  onSome: (profile) => profile.models.map((model) => ({
+    selection: `${provider}:${model.id}`,
+    ...Option.match(profile.label, { onNone: () => ({}), onSome: (label) => ({ label: `${label} \xB7 ${model.id}` }) }),
+    provider,
+    credential: credential.type,
+    input: routeReadsImages(provider, model, credential, endpoints) ? ["text", "image"] : ["text"],
+    ...Option.match(routeLimits(provider, model, credential, endpoints, settings), { onNone: () => ({}), onSome: (limits) => ({ limits }) })
+  }))
+})), reasoningEffortsFor = (selection) => Option.match(modelProfileOf(selection), { onNone: () => [], onSome: (model) => model.efforts }), publicReasoningEffort = (effort) => effort === "xhigh" || effort === "max" ? "high" : effort === "none" ? "low" : effort, ConfiguredModelCatalogLive = Layer.effect(ModelCatalog, Effect.all({ auth: AuthStore, endpoints: Effect.service(CurrentModelEndpoints), settings: Effect.service(CurrentModelSettings) }, { concurrency: 1 }).pipe(Effect.map(({ auth, endpoints, settings }) => ({
+  list: auth.all.pipe(Effect.tapError((error) => Effect.logWarning("the model catalog could not read the stored credentials; it lists none of them", error)), Effect.orElseSucceed(() => new Map), Effect.map((credentials) => configuredModelCatalog(credentials, endpoints, settings)))
+}))));

package/dist/llm/openAiCodex.d.ts

@@ -1,14 +1,25 @@
-import { LanguageModel } from "effect/ai";
+import { AiError, LanguageModel } from "effect/ai";
 import { HttpClient } from "effect/http";
-import { Effect, Redacted } from "effect";
+import { Effect, Option, Redacted, Schema } from "effect";
+import type { ReasoningEffortType } from "@xandreed/core";
+import type { WebSocketProxy } from "../ports/models-transport.port.js";
 export declare const OPENAI_CODEX_API_URL = "https://chatgpt.com/backend-api/codex";
-type Json = Record<string, unknown>;
-/** Translate the standard Responses request into the Codex subscription dialect. */
-export declare const toOpenAiCodexRequestBody: (body: unknown, reasoningEffort?: "none" | "low" | "medium" | "high" | "xhigh" | "max") => Json;
-export declare const mapOpenAiCodexError: (model: string, error: unknown) => unknown;
+/**
+ * Translate the standard Responses request into the Codex subscription
+ * dialect. A body that is not a Responses request object reads as an empty
+ * one.
+ */
+export declare const toOpenAiCodexRequestBody: (body: unknown, reasoningEffort?: ReasoningEffortType) => Schema.JsonObject;
+/**
+ * Refine structured subscription errors before the legacy protocol fallback.
+ * Keep concrete reason classes and HTTP/provider evidence; explicit semantic
+ * stamps prevent a protocol failure from becoming a model-output corrective.
+ */
+export declare const mapOpenAiCodexError: <E>(_model: string, error: E) => E | AiError.AiError;
 export declare const makeOpenAiCodexLanguageModel: (args: {
     readonly model: string;
     readonly accessToken: Redacted.Redacted<string>;
     readonly accountId: string;
+    /** How the WebSocket reaches ChatGPT (`ModelsTransport.webSocketAgent`); default: directly. */
+    readonly webSocketProxy?: Option.Option<WebSocketProxy>;
 }) => Effect.Effect<LanguageModel.LanguageModel, never, HttpClient.HttpClient>;
-export {};