@xandreed/plugin-models 0.13.0 → 0.15.0

package/dist/llm/providers.d.ts

@@ -1,44 +1,140 @@
-import { LanguageModel } from "effect/ai";
+import { AiError, LanguageModel, Prompt } from "effect/ai";
 import { HttpClient } from "effect/http";
-import { Effect, Redacted } from "effect";
-import type { Scope } from "effect";
-import { AuthError } from "@xandreed/core";
-import type { Credential, ModelSelection } from "@xandreed/core";
+import { Config, Effect, Option, Redacted, Result } from "effect";
+import type { Context, Schema, Scope } from "effect";
+import { AuthError } from "../ports/auth-store.port.js";
+import type { ModelCallPolicy, ModelSelection } from "@xandreed/core";
+import type { Credential } from "../ports/auth-store.port.js";
+import { usesOpenCodeResponses } from "./modelCatalog.js";
+import type { OpenAiCodexSessions } from "./openAiCodexWebSocket.js";
+import type { Route } from "./provider-profile.entity.js";
+import type { ModelEndpoint, ModelEndpoints } from "../ports/model-endpoints.port.js";
+import { ModelsTransport } from "../ports/models-transport.port.js";
+import { ModelSettingsError } from "./model-settings.entity.js";
+import type { ModelSettingsMap } from "./model-settings.entity.js";
+import type { ThinkingPrefixMismatch } from "./thinking-binding.entity.js";
 /**
  * Per-provider `LanguageModel` construction. Built PER REQUEST from a
  * freshly-resolved key (never captured at layer build), so a credential or
  * model switch applies on the next call.
  *
- * v1 providers: opencode (OpenAI-compatible gateway — the default), google
- * (Gemini's OpenAI-compatible endpoint), anthropic (api key or subscription
- * OAuth), openai (api key), openai-codex (subscription OAuth). A configured
- * endpoint, or a `local` credential with a `baseUrl`, sends its provider's
- * models to that OpenAI-compatible URL, with or without a key.
+ * The built-in providers are their profiles (`PROVIDER_PROFILES`): opencode
+ * (OpenAI-compatible gateway — the default), google (Gemini's
+ * OpenAI-compatible endpoint), anthropic (api key or subscription OAuth),
+ * openai (api key), openai-codex (subscription OAuth). A model is built by
+ * its route, one builder each. A configured endpoint, or a `local`
+ * credential with a `baseUrl`, sends its provider's models to that
+ * OpenAI-compatible URL, with or without a key.
  */
-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";
-/** Pure protocol routing decision; provider details stay inside this adapter. */
-export declare const usesOpenCodeResponses: (modelId: string) => boolean;
+export { GOOGLE_CHAT_URL, OPENCODE_CHAT_URL, OPENCODE_RESPONSES_API_URL } from "./provider-profile.entity.functions.js";
+export { usesOpenCodeResponses };
 export interface BuiltProvider {
     readonly svc: LanguageModel.LanguageModel;
     /** Anthropic subscription auth requires the Claude Code system block first. */
     readonly prependClaudeCode: boolean;
+    /** The route sends images; when it does not, `buildProvider` has the model send them as label lines. */
+    readonly images: boolean;
+    /** The route the model is sent over: a configured endpoint's and a `local` credential's URL are `compat`. */
+    readonly route: Route["_tag"];
 }
+/** The options of a model call, as far as the plugin rewrites them: the prompt. */
+export interface PromptOptions {
+    readonly prompt: Prompt.RawInput;
+    readonly toolChoice?: LanguageModel.ToolChoice<string> | undefined;
+}
+/** A call's options with the prompt `f` made of it; every other option is kept. */
+export declare const withPrompt: <O extends PromptOptions>(options: O, f: (prompt: Prompt.Prompt) => Prompt.Prompt) => Omit<O, "prompt"> & {
+    readonly prompt: Prompt.Prompt;
+};
 /** Prepend the Claude Code system block (subscription-auth requirement). */
-export declare const prependClaudeCode: (options: unknown) => unknown;
-/**
- * Anthropic prompt caching is OPT-IN per request: stamp ephemeral
- * `cache_control` breakpoints on the last system message + the last two
- * non-system messages. Marker placement is not part of Anthropic's content
- * hash, so the markers moving forward each turn never invalidates earlier
- * prefixes. Messages already carrying an explicit `cacheControl` are left
- * alone.
- */
-export declare const withAnthropicCacheBreakpoints: (options: unknown) => unknown;
+export declare const prependClaudeCode: <O extends PromptOptions>(options: O) => Omit<O, "prompt"> & {
+    readonly prompt: Prompt.Prompt;
+};
 /** `<url>/chat/completions` of an OpenAI-compatible base URL. */
 export declare const chatCompletionsUrl: (baseUrl: string) => string;
-/** Preserve adapter descriptors and describe the public configuration of SDK-backed models. */
-export declare const buildProvider: (selection: ModelSelection, credential: Credential | undefined, key: Redacted.Redacted<string> | undefined) => Effect.Effect<BuiltProvider, AuthError, HttpClient.HttpClient | Scope.Scope>;
+/**
+ * An endpoint's own key: `apiKey`, then the variable `apiKeyEnv` names, read
+ * with `Config` from the current ConfigProvider (the process environment
+ * unless the host provides another; the environment's reads an empty
+ * variable as unset). An empty `apiKey` is still the endpoint's own: it
+ * sends no key, and the AuthStore's is not used. Fails with the
+ * ConfigError when the provider cannot be read.
+ */
+export declare const endpointOwnKey: (endpoint: ModelEndpoint) => Effect.Effect<Option.Option<Redacted.Redacted<string>>, Config.ConfigError>;
+/** The transport the plugin was built over, if any: the compat client's fetch goes through it. */
+type Transport = Option.Option<Context.Service.Shape<typeof ModelsTransport>>;
+/**
+ * What a provider is built over besides its selection and credential: the
+ * configured endpoints, the transport, and the OpenAI subscription's
+ * session cache (`None` keeps one per built model). The routed models read
+ * them once, where their layer is built, and build every call's provider
+ * over them ({@link buildProviderOver}).
+ */
+export interface ProviderServices {
+    readonly endpoints: ModelEndpoints;
+    readonly modelSettings: ModelSettingsMap;
+    readonly transport: Transport;
+    readonly managedTransport: Transport;
+    readonly sessions: Option.Option<OpenAiCodexSessions>;
+    /** What a request to a model that binds thinking says about a changed prefix (`thinkingPrefixMismatch`). */
+    readonly thinkingPrefixMismatch: ThinkingPrefixMismatch;
+}
+/** The provider services where this runs: `CurrentModelEndpoints`, `CurrentModelSettings`, `ModelsTransport` if provided, `CurrentOpenAiCodexSessions`, `CurrentThinkingPrefixMismatch`. */
+export declare const providerServices: Effect.Effect<ProviderServices>;
+type MessagesEndpoint = Extract<ModelEndpoint, {
+    readonly api: "anthropic-messages";
+}>;
+/** Accept a root, a proxy prefix or a base ending in /v1, without doubling the Messages path. */
+export declare const anthropicBaseUrl: (base: string) => string;
+/** A model configuration failure is not an authentication failure or a retryable provider outage. */
+export declare const modelSettingsFailure: (error: ModelSettingsError) => AiError.AiError;
+/** Public Messages controls shared by provider construction and durable routing descriptions; no credentials or client IO. */
+export declare const resolveMessagesConfiguration: (selection: ModelSelection, modelSettings: ModelSettingsMap, policy: Option.Option<ModelCallPolicy>, thinkingPrefixMismatch: ThinkingPrefixMismatch, endpoint: Option.Option<MessagesEndpoint>) => Result.Result<{
+    resolved: {
+        readonly selection: string;
+        readonly maxOutputTokens: number;
+        readonly effort: Option.Option<"low" | "medium" | "high" | "xhigh" | "max">;
+        readonly thinking: Option.Option<{
+            readonly _tag: "Off";
+        } | {
+            readonly _tag: "Adaptive";
+            readonly display?: "omitted" | "summarized";
+        } | {
+            readonly _tag: "Budget";
+            readonly budgetTokens: number;
+            readonly display?: "omitted" | "summarized";
+        } | {
+            readonly _tag: "BetweenTools";
+        }>;
+        readonly promptCache: {
+            readonly _tag: "Auto";
+            readonly ttl: "5m" | "1h";
+        } | {
+            readonly _tag: "TopLevel";
+            readonly ttl: "5m" | "1h";
+        } | {
+            readonly _tag: "Off";
+        };
+        readonly limits?: {
+            readonly maxOutputTokens?: number;
+            readonly contextWindow?: number;
+        };
+    };
+    binding: Option.Option<"error" | "drop_block">;
+    wire: Schema.JsonObject;
+    settings: Schema.JsonObject;
+}, ModelSettingsError>;
+/**
+ * {@link buildProvider} over the given provider services, not those where
+ * it runs: a routed model builds each call's provider over the services its
+ * layer was built with.
+ */
+export declare const buildProviderOver: (services: ProviderServices) => (selection: ModelSelection, credential: Credential | undefined, key: Redacted.Redacted<string> | undefined) => Effect.Effect<BuiltProvider, AuthError | ModelSettingsError, HttpClient.HttpClient | Scope.Scope>;
+/**
+ * Preserve adapter descriptors and describe the public configuration of
+ * SDK-backed models. On a route that reads no images (the model's profile,
+ * a configured endpoint's `images`), every request is sent with its images
+ * as label lines (`promptWithImageLabels`) instead of a provider error.
+ * Built over the provider services where it runs (`providerServices`).
+ */
+export declare const buildProvider: (selection: ModelSelection, credential: Credential | undefined, key: Redacted.Redacted<string> | undefined) => Effect.Effect<BuiltProvider, AuthError | ModelSettingsError, HttpClient.HttpClient | Scope.Scope>;