@xandreed/plugin-models 0.13.0 → 0.15.0

package/dist/ports/auth-store.port.d.ts

@@ -0,0 +1,73 @@
+import { Context, Option, Schema } from "effect";
+import type { Effect, Redacted } from "effect";
+import type { ProviderId } from "@xandreed/core";
+/**
+ * A stored provider credential: a raw API key, an OAuth subscription (with
+ * refresh material and absolute expiry, epoch ms), or a local provider that
+ * needs no key. Its secrets (`key`, `access`, `refresh`) are `Redacted`, so
+ * they print as `<redacted>` in errors, logs and fingerprints; unwrap one
+ * with `Redacted.value` only where a request is built. The encoded form is
+ * the on-disk `auth.json` vocabulary the previous line established, secrets
+ * in the clear, so existing credentials keep working. Store a credential
+ * through `Schema.encodeEffect(Credential)`, never `JSON.stringify`, which
+ * writes `"<redacted>"` in place of each secret.
+ *
+ * @public
+ */
+export declare const Credential: Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"api_key">;
+    readonly key: Schema.RedactedFromValue<Schema.String>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"oauth">;
+    readonly access: Schema.RedactedFromValue<Schema.String>;
+    readonly refresh: Schema.RedactedFromValue<Schema.String>;
+    readonly expires: Schema.Number;
+    readonly accountId: Schema.optionalKey<Schema.String>;
+    readonly installationId: Schema.optionalKey<Schema.String>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"local">;
+    readonly baseUrl: Schema.optionalKey<Schema.String>;
+}>]>;
+export type Credential = typeof Credential.Type;
+declare const AuthError_base: Schema.Class<AuthError, Schema.TaggedStruct<"AuthError", {
+    readonly provider: Schema.String;
+    readonly message: Schema.String;
+    /**
+     * `auth.corrupt`: the store's backing data could not be read or decoded.
+     * Nothing was read as absent and nothing was written over it.
+     */
+    readonly code: Schema.optionalKey<Schema.Literal<"auth.corrupt">>;
+}>, import("effect/Cause").YieldableError>;
+export declare class AuthError extends AuthError_base {
+}
+declare const AuthStore_base: Context.ServiceClass<AuthStore, "@xandreed/core/AuthStore", {
+    readonly all: Effect.Effect<ReadonlyMap<string, Credential>, AuthError>;
+    readonly get: (p: ProviderId) => Effect.Effect<Option.Option<Credential>, AuthError>;
+    readonly resolveKey: (p: ProviderId) => Effect.Effect<Option.Option<Redacted.Redacted<string>>, AuthError>;
+    /** Persist a credential (a login). */
+    readonly set: (p: ProviderId, credential: Credential) => Effect.Effect<void, AuthError>;
+    /** Remove a provider's credential everywhere it is stored (a logout). */
+    readonly remove: (p: ProviderId) => Effect.Effect<void, AuthError>;
+}>;
+/**
+ * The credential store, read lazily per request: `resolveKey` returns a
+ * usable secret (refreshing a near-expiry OAuth token first, and persisting
+ * it where the store keeps credentials), so a credential added mid-session
+ * takes effect on the next call with no restart. `None` means the provider
+ * is not configured. Every secret it hands out, through `get` and `all` as
+ * through `resolveKey`, is `Redacted`.
+ *
+ * One refresh of a credential runs at a time: concurrent calls on one
+ * expired token send one token request and share its result. A `set` or
+ * `remove` made while that request is in flight wins over the refreshed
+ * token. A store whose backing data cannot be read or decoded fails every
+ * call with an `AuthError` of code `auth.corrupt` instead of reading it as
+ * empty, so no write replaces credentials it could not read.
+ * `authStoreConformance` (`@xandreed/plugin-models/conformance`) checks a
+ * store against this contract. Its key stays `@xandreed/core/AuthStore`, the
+ * package it was first declared in: plugins' `provides` and hosts' bindings
+ * name it, so it never changes.
+ */
+export declare class AuthStore extends AuthStore_base {
+}
+export {};

package/dist/ports/auth-store.port.js

@@ -0,0 +1,24 @@
+import { Context, Option, Schema } from "effect";
+const Secret = Schema.RedactedFromValue(Schema.String);
+export const Credential = Schema.Union([
+  Schema.Struct({ type: Schema.Literal("api_key"), key: Secret }),
+  Schema.Struct({
+    type: Schema.Literal("oauth"),
+    access: Secret,
+    refresh: Secret,
+    expires: Schema.Number,
+    accountId: Schema.optionalKey(Schema.String),
+    installationId: Schema.optionalKey(Schema.String)
+  }),
+  Schema.Struct({ type: Schema.Literal("local"), baseUrl: Schema.optionalKey(Schema.String) })
+]);
+
+export class AuthError extends Schema.TaggedError()("AuthError", {
+  provider: Schema.String,
+  message: Schema.String,
+  code: Schema.optionalKey(Schema.Literal("auth.corrupt"))
+}) {
+}
+
+export class AuthStore extends Context.Service()("@xandreed/core/AuthStore") {
+}

package/dist/ports/host-credentials.port.d.ts

@@ -0,0 +1,22 @@
+import { Context } from "effect";
+import type { Effect, Option } from "effect";
+import type { ProviderId } from "@xandreed/core";
+import type { AuthError } from "./auth-store.port.js";
+import type { CredentialInput } from "../auth/credential-input.entity.js";
+declare const HostCredentials_base: Context.ServiceClass<HostCredentials, "@xandreed/plugin-models/HostCredentials", {
+    readonly load: Effect.Effect<ReadonlyMap<string, CredentialInput>, AuthError>;
+    readonly save: (provider: ProviderId, credential: Option.Option<CredentialInput>) => Effect.Effect<void, AuthError>;
+}>;
+/**
+ * Credentials a host keeps itself (a secrets manager, a database, its own
+ * session store), for the models plugin with `storage: "memory"`. `load` is
+ * read once, when the plugin starts; `save` is called after every change the
+ * AuthStore makes — a login (`set`), a logout (`None`), an OAuth token
+ * refreshed in memory — so the host can keep the new value. Secrets cross
+ * this port `Redacted`. A failed `save` fails a login or logout (memory is
+ * left as it was) but not a refresh: the refreshed token is already the
+ * only valid one, so it stays in memory and the failure is logged.
+ */
+export declare class HostCredentials extends HostCredentials_base {
+}
+export {};

package/dist/ports/host-credentials.port.js

@@ -0,0 +1,4 @@
+import { Context } from "effect";
+
+export class HostCredentials extends Context.Service()("@xandreed/plugin-models/HostCredentials") {
+}

package/dist/ports/model-call-completion.port.d.ts

@@ -0,0 +1,9 @@
+import { Context, Option } from "effect";
+import type { ModelSelection } from "@xandreed/core";
+/** Private execution-time purpose; utilities provide Helper without recording another call. */
+export declare const CurrentModelCallPurpose: Context.Reference<"Loop" | "Helper">;
+/** Private invocation metadata; a routed object call can use a provider's text implementation. */
+export declare const CurrentModelCallMethod: Context.Reference<"Text" | "Object" | "Stream">;
+export declare const CurrentModelCallSelection: Context.Reference<Option.Option<ModelSelection>>;
+/** Identifies which logical budget owns inherited invocation metadata. */
+export declare const CurrentModelCallMetadataOwner: Context.Reference<Option.Option<string & import("effect/Brand").Brand<"ModelCallId">>>;

package/dist/ports/model-call-completion.port.js

@@ -0,0 +1,2 @@
+import { Context, Option } from "effect";
+export const CurrentModelCallPurpose = Context.Reference("@xandreed/plugin-models/CurrentModelCallPurpose", { defaultValue: () => "Loop" }), CurrentModelCallMethod = Context.Reference("@xandreed/plugin-models/CurrentModelCallMethod", { defaultValue: () => "Text" }), CurrentModelCallSelection = Context.Reference("@xandreed/plugin-models/CurrentModelCallSelection", { defaultValue: () => Option.none() }), CurrentModelCallMetadataOwner = Context.Reference("@xandreed/plugin-models/CurrentModelCallMetadataOwner", { defaultValue: () => Option.none() });

package/dist/ports/model-endpoints.port.d.ts

@@ -1,33 +1,80 @@
 import { Context, Schema } from "effect";
+/** A base URL using chat completions, or an explicit Anthropic Messages protocol. @public */
+export declare const ModelEndpoint: Schema.Union<readonly [Schema.Struct<{
+    /** Absent keeps the existing chat-completions protocol. */
+    readonly api: Schema.optionalKey<Schema.Literal<"chat-completions">>;
+    readonly standardOnly: Schema.optionalKey<Schema.Boolean>;
+    readonly url: Schema.String;
+    readonly apiKey: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
+    readonly apiKeyEnv: Schema.optionalKey<Schema.String>;
+    readonly images: Schema.optionalKey<Schema.Boolean>;
+}>, Schema.Struct<{
+    readonly api: Schema.Literal<"anthropic-messages">;
+    /** The API key is opaque in either header; omission uses x-api-key. */
+    readonly auth: Schema.optionalKey<Schema.Literals<readonly ["x-api-key", "bearer"]>>;
+    /** False disables framework caching and refuses caller cache controls. */
+    readonly cacheControl: Schema.optionalKey<Schema.Boolean>;
+    /** Preserve the pinned SDK's version by default; an explicit version is sent verbatim. */
+    readonly apiVersion: Schema.optionalKey<Schema.String>;
+    /** Added to the SDK's own beta flags, in order with duplicates removed. */
+    readonly betas: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly url: Schema.String;
+    readonly apiKey: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
+    readonly apiKeyEnv: Schema.optionalKey<Schema.String>;
+    readonly images: Schema.optionalKey<Schema.Boolean>;
+}>]>;
+export type ModelEndpoint = typeof ModelEndpoint.Type;
 /**
- * An OpenAI-compatible endpoint a host names in configuration: the model
- * `<name>:<model id>` is sent to `<url>/chat/completions`. The key is
- * optional — a local server or a private gateway may need none. It comes
- * from `apiKey`, then the environment variable `apiKeyEnv` names, then the
- * AuthStore's key for `<name>`; with none, no Authorization header is sent.
- * `standardOnly` (default true) sends only standard chat-completions fields.
+ * Endpoints by provider name; a name that matches a built-in provider replaces it.
+ *
+ * @public
  */
-export declare const ModelEndpoint: Schema.Struct<{
+export declare const ModelEndpoints: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Struct<{
+    /** Absent keeps the existing chat-completions protocol. */
+    readonly api: Schema.optionalKey<Schema.Literal<"chat-completions">>;
+    readonly standardOnly: Schema.optionalKey<Schema.Boolean>;
     readonly url: Schema.String;
-    readonly apiKey: Schema.optionalKey<Schema.String>;
+    readonly apiKey: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
     readonly apiKeyEnv: Schema.optionalKey<Schema.String>;
-    readonly standardOnly: Schema.optionalKey<Schema.Boolean>;
-}>;
-export type ModelEndpoint = typeof ModelEndpoint.Type;
-/** Endpoints by provider name; a name that matches a built-in provider replaces it. */
-export declare const ModelEndpoints: Schema.$Record<Schema.String, Schema.Struct<{
+    readonly images: Schema.optionalKey<Schema.Boolean>;
+}>, Schema.Struct<{
+    readonly api: Schema.Literal<"anthropic-messages">;
+    /** The API key is opaque in either header; omission uses x-api-key. */
+    readonly auth: Schema.optionalKey<Schema.Literals<readonly ["x-api-key", "bearer"]>>;
+    /** False disables framework caching and refuses caller cache controls. */
+    readonly cacheControl: Schema.optionalKey<Schema.Boolean>;
+    /** Preserve the pinned SDK's version by default; an explicit version is sent verbatim. */
+    readonly apiVersion: Schema.optionalKey<Schema.String>;
+    /** Added to the SDK's own beta flags, in order with duplicates removed. */
+    readonly betas: Schema.optionalKey<Schema.$Array<Schema.String>>;
     readonly url: Schema.String;
-    readonly apiKey: Schema.optionalKey<Schema.String>;
+    readonly apiKey: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
     readonly apiKeyEnv: Schema.optionalKey<Schema.String>;
-    readonly standardOnly: Schema.optionalKey<Schema.Boolean>;
-}>>;
+    readonly images: Schema.optionalKey<Schema.Boolean>;
+}>]>>;
 export type ModelEndpoints = typeof ModelEndpoints.Type;
-/** The endpoints the models plugin was configured with; none by default. */
+/**
+ * The endpoints the models plugin was configured with; none by default.
+ *
+ * @public
+ */
 export declare const CurrentModelEndpoints: Context.Reference<{
     readonly [x: string]: {
         readonly url: string;
-        readonly apiKey?: string;
-        readonly apiKeyEnv?: string;
+        readonly images?: boolean;
+        readonly apiKey?: string | import("effect/Redacted").Redacted<string>;
+        readonly api?: "chat-completions";
         readonly standardOnly?: boolean;
+        readonly apiKeyEnv?: string;
+    } | {
+        readonly url: string;
+        readonly api: "anthropic-messages";
+        readonly images?: boolean;
+        readonly apiKey?: string | import("effect/Redacted").Redacted<string>;
+        readonly auth?: "x-api-key" | "bearer";
+        readonly apiKeyEnv?: string;
+        readonly cacheControl?: boolean;
+        readonly apiVersion?: string;
+        readonly betas?: readonly string[];
     };
 }>;

package/dist/ports/model-endpoints.port.js

@@ -1,9 +1,27 @@
 import { Context, Schema } from "effect";
-export const ModelEndpoint = Schema.Struct({
+const endpointFields = {
   url: Schema.String,
-  apiKey: Schema.optionalKey(Schema.String),
+  apiKey: Schema.optionalKey(Schema.Union([
+    Schema.String,
+    Schema.Redacted(Schema.String).annotate({ message: "apiKey is a string or a Redacted string" })
+  ]).annotate({ message: "apiKey is a string or a Redacted string" })),
   apiKeyEnv: Schema.optionalKey(Schema.String),
-  standardOnly: Schema.optionalKey(Schema.Boolean)
-}), ModelEndpoints = Schema.Record(Schema.String, ModelEndpoint), CurrentModelEndpoints = Context.Reference("@xandreed/plugin-models/CurrentModelEndpoints", {
+  images: Schema.optionalKey(Schema.Boolean)
+};
+export const ModelEndpoint = Schema.Union([
+  Schema.Struct({
+    ...endpointFields,
+    api: Schema.optionalKey(Schema.Literal("chat-completions")),
+    standardOnly: Schema.optionalKey(Schema.Boolean)
+  }).annotate({ messageUnexpectedKey: "not an option of a chat-completions endpoint" }),
+  Schema.Struct({
+    ...endpointFields,
+    api: Schema.Literal("anthropic-messages"),
+    auth: Schema.optionalKey(Schema.Literals(["x-api-key", "bearer"])),
+    cacheControl: Schema.optionalKey(Schema.Boolean),
+    apiVersion: Schema.optionalKey(Schema.String.check(Schema.isPattern(/^\d{4}-\d{2}-\d{2}$/))),
+    betas: Schema.optionalKey(Schema.Array(Schema.String.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]*$/))))
+  }).annotate({ messageUnexpectedKey: "not an option of an anthropic-messages endpoint" })
+]).annotate({ messageUnexpectedKey: "not an option of a model endpoint" }), ModelEndpoints = Schema.Record(Schema.String, ModelEndpoint), CurrentModelEndpoints = Context.Reference("@xandreed/plugin-models/CurrentModelEndpoints", {
   defaultValue: () => ({})
 });

package/dist/ports/model-retry-policy.port.d.ts

@@ -0,0 +1,17 @@
+import { Context, Option } from "effect";
+import type { ModelRequestCall } from "../transport/resilient-http-client.adapter.js";
+/** Read when a logical model call executes; the complete policy overrides the defaults. @public */
+export declare const CurrentModelRetryPolicy: Context.Reference<{
+    readonly maxAttempts: number;
+    readonly requestTimeoutMs: number;
+    readonly bodyIdleTimeoutMs: number;
+    readonly totalTimeoutMs: number;
+    readonly retryAfterMaxMs: number;
+    readonly backoff: {
+        readonly initialMs: number;
+        readonly maxMs: number;
+        readonly jitter: number;
+    };
+}>;
+/** Private per-call counter/deadline, shared only by its primary and fallback rung. */
+export declare const CurrentModelRequestCall: Context.Reference<Option.Option<ModelRequestCall>>;

package/dist/ports/model-retry-policy.port.js

@@ -0,0 +1,3 @@
+import { Context, Option } from "effect";
+import { modelRetryDefaults } from "../llm/model-retry-policy.entity.js";
+export const CurrentModelRetryPolicy = Context.Reference("@xandreed/plugin-models/CurrentModelRetryPolicy", { defaultValue: () => modelRetryDefaults }), CurrentModelRequestCall = Context.Reference("@xandreed/plugin-models/CurrentModelRequestCall", { defaultValue: () => Option.none() });

package/dist/ports/model-settings.port.d.ts

@@ -0,0 +1,32 @@
+import { Context } from "effect";
+/** Static per-model settings captured where the models layer is built. @public */
+export declare const CurrentModelSettings: Context.Reference<{
+    readonly [x: string]: {
+        readonly effort?: "none" | "low" | "medium" | "high" | "xhigh" | "max";
+        readonly limits?: {
+            readonly maxOutputTokens?: number;
+            readonly contextWindow?: number;
+        };
+        readonly thinking?: {
+            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";
+        };
+    };
+}>;

package/dist/ports/model-settings.port.js

@@ -0,0 +1,4 @@
+import { Context } from "effect";
+export const CurrentModelSettings = Context.Reference("@xandreed/plugin-models/CurrentModelSettings", {
+  defaultValue: () => ({})
+});

package/dist/ports/models-transport.port.d.ts

@@ -0,0 +1,53 @@
+import { Context, Option } from "effect";
+import type { Effect, Redacted } from "effect";
+import type { Agent } from "node:http";
+import type { ProxyUnsupported } from "../transport/http-proxy.entity.js";
+/**
+ * A fetch for the models plugin's HTTP calls: a URL (string or `URL`) and a
+ * `RequestInit`, as the provider clients, the OpenAI-compatible client and
+ * the OAuth token requests call it. Any `fetch` is one.
+ */
+export type ModelsFetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * How a WebSocket reaches its target. `Agent` is for Node only: the agent
+ * the `ws` client connects with (one that tunnels through the proxy with
+ * CONNECT, or a plain one for a direct connection). `Proxy` is for Bun only:
+ * the proxy URL Bun's own `WebSocket` takes as its `proxy` option. A route
+ * the runtime cannot use (`Proxy` outside Bun, `Agent` on Bun, whose `ws`
+ * stand-in takes neither) fails the call rather than connecting past the
+ * proxy.
+ *
+ * @public
+ */
+export type WebSocketProxy = {
+    readonly _tag: "Agent";
+    readonly agent: Agent;
+} | {
+    readonly _tag: "Proxy";
+    readonly url: Redacted.Redacted<string>;
+};
+declare const ModelsTransport_base: Context.ServiceClass<ModelsTransport, "@xandreed/plugin-models/ModelsTransport", {
+    readonly fetch: ModelsFetch;
+    readonly webSocketAgent?: (target: URL) => Effect.Effect<Option.Option<WebSocketProxy>, ProxyUnsupported>;
+}>;
+/**
+ * The network path of the models plugin: every HTTP call it makes (the
+ * provider SDKs, the OpenAI-compatible client, OAuth token requests) goes
+ * through `fetch`, and the OpenAI subscription's WebSocket asks
+ * `webSocketAgent` how to reach its target: `None` connects the runtime's
+ * default way (direct, unless the runtime applies an environment proxy
+ * itself, as Node's global agents do under `NODE_USE_ENV_PROXY`),
+ * `ProxyUnsupported` refuses (a proxy applies that this runtime cannot
+ * tunnel a WebSocket through). Without `webSocketAgent`, WebSockets connect
+ * the default way. `ModelsTransportLive` builds one from a proxy setting and
+ * the environment; a host provides its own (a fetch with client
+ * certificates, say) through `Agent.define({ services })`.
+ */
+export declare class ModelsTransport extends ModelsTransport_base {
+}
+/** Internal provenance: only this exact managed direct instance yields to an explicit call-local fetch. */
+export declare const CurrentManagedModelsTransport: Context.Reference<Option.Option<{
+    readonly fetch: ModelsFetch;
+    readonly webSocketAgent?: (target: URL) => Effect.Effect<Option.Option<WebSocketProxy>, ProxyUnsupported>;
+}>>;
+export {};

package/dist/ports/models-transport.port.js

@@ -0,0 +1,7 @@
+import { Context, Option } from "effect";
+
+export class ModelsTransport extends Context.Service()("@xandreed/plugin-models/ModelsTransport") {
+}
+export const CurrentManagedModelsTransport = Context.Reference("@xandreed/plugin-models/CurrentManagedModelsTransport", {
+  defaultValue: Option.none
+});

package/dist/ports/prompt-cache-frame.port.d.ts

@@ -0,0 +1,21 @@
+import { Context } from "effect";
+/** A captured SDK client reads this immutable frame in the invoking call's fiber. */
+export declare const CurrentPromptCacheFrame: Context.Reference<{
+    readonly candidates: readonly {
+        readonly control: {
+            readonly type: "ephemeral";
+            readonly ttl?: "5m" | "1h";
+        };
+        readonly priority: number;
+    }[];
+    readonly policy: {
+        readonly _tag: "Auto";
+        readonly ttl: "5m" | "1h";
+    } | {
+        readonly _tag: "TopLevel";
+        readonly ttl: "5m" | "1h";
+    } | {
+        readonly _tag: "Off";
+    };
+    readonly capability: boolean;
+}>;

package/dist/ports/prompt-cache-frame.port.js

@@ -0,0 +1,4 @@
+import { Context } from "effect";
+export const CurrentPromptCacheFrame = Context.Reference("@xandreed/plugin-models/CurrentPromptCacheFrame", {
+  defaultValue: () => ({ candidates: [], policy: { _tag: "Off" }, capability: !0 })
+});

package/dist/ports/settings-store.port.d.ts

@@ -0,0 +1,70 @@
+import { Context, Effect, Option, Schema } from "effect";
+declare const EngineSettings_base: Schema.Class<EngineSettings, Schema.Struct<{
+    readonly model: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<string, string, never, never>>>;
+    readonly codeModel: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<string, string, never, never>>>;
+    readonly fastModel: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<string, string, never, never>>>;
+    readonly fallbackModel: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<string, string, never, never>>>;
+    readonly maxAttempts: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<number, number, never, never>>>;
+    readonly budgetMillis: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<number, number, never, never>>>;
+    /** Selected after the model because the accepted levels are model-specific. */
+    readonly reasoningEffort: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<"none" | "low" | "medium" | "high" | "xhigh" | "max", "none" | "low" | "medium" | "high" | "xhigh" | "max", never, never>>>;
+    readonly codeReasoningEffort: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<"none" | "low" | "medium" | "high" | "xhigh" | "max", "none" | "low" | "medium" | "high" | "xhigh" | "max", never, never>>>;
+    readonly fastReasoningEffort: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<"none" | "low" | "medium" | "high" | "xhigh" | "max", "none" | "low" | "medium" | "high" | "xhigh" | "max", never, never>>>;
+}>, {}>;
+/** @public */
+export declare class EngineSettings extends EngineSettings_base {
+}
+declare const SettingsError_base: Schema.Class<SettingsError, Schema.TaggedStruct<"SettingsError", {
+    readonly message: Schema.String;
+    /**
+     * `settings.corrupt`: the store's backing data could not be read or
+     * decoded. Nothing was read as defaults and nothing was written over it.
+     */
+    readonly code: Schema.optionalKey<Schema.Literal<"settings.corrupt">>;
+}>, import("effect/Cause").YieldableError>;
+/** @public */
+export declare class SettingsError extends SettingsError_base {
+}
+/**
+ * The three model roles a selection can be persisted under.
+ *
+ * @public
+ */
+export type ModelRole = "general" | "code" | "fast";
+/** The non-role keys the keyed setter may write — a closed vocabulary, so a
+ *  typo can never land a dead key in the user's config.
+ *
+ * @public
+ */
+export declare const SETTINGS_KEYS: readonly ["fallbackModel", "maxAttempts", "budgetMillis", "reasoningEffort", "codeReasoningEffort", "fastReasoningEffort"];
+/** @public */
+export type SettingsKey = (typeof SETTINGS_KEYS)[number];
+declare const SettingsStore_base: Context.ServiceClass<SettingsStore, "@xandreed/core/SettingsStore", {
+    readonly load: Effect.Effect<EngineSettings, SettingsError>;
+    /** Persist one role's model selection (a role choice); `None` clears
+     *  the role so it falls back to its default again. A selection that is
+     *  not `"<provider>:<modelId>"` fails with a `SettingsError` and writes
+     *  nothing. */
+    readonly setRole: (role: ModelRole, selection: Option.Option<string>) => Effect.Effect<void, SettingsError>;
+    /** Persist one non-role key from its STRING form (a settings edit): the
+     *  adapter validates + coerces per key ("true", "3", "provider:model")
+     *  and rejects a value that doesn't parse with a `SettingsError`,
+     *  writing nothing; `None` clears the key. */
+    readonly set: (key: SettingsKey, value: Option.Option<string>) => Effect.Effect<void, SettingsError>;
+}>;
+/**
+ * Read-through settings port. `load` re-reads the backing store on every call
+ * so a value changed mid-session takes effect on the next turn — callers must
+ * not cache the result across turns. A store may be read-only: then
+ * `setRole` and `set` fail with a `SettingsError` and write nothing. A store
+ * whose backing data cannot be read or decoded fails `load` and every write
+ * with a `SettingsError` of code `settings.corrupt` instead of reading it as
+ * defaults, so no write replaces settings it could not read.
+ * `settingsStoreConformance` (`@xandreed/plugin-models/conformance`) checks
+ * a store against this contract. Its key stays `@xandreed/core/SettingsStore`,
+ * the package it was first declared in: plugins' `provides` and hosts'
+ * bindings name it, so it never changes.
+ */
+export declare class SettingsStore extends SettingsStore_base {
+}
+export {};

package/dist/ports/settings-store.port.js

@@ -0,0 +1,33 @@
+import { Context, Effect, Option, Schema } from "effect";
+import { ReasoningEffort } from "@xandreed/core";
+const optionField = (schema) => Schema.OptionFromOptional(schema).pipe(Schema.withConstructorDefault(Effect.succeed(Option.none())));
+
+export class EngineSettings extends Schema.Class("EngineSettings")({
+  model: optionField(Schema.String),
+  codeModel: optionField(Schema.String),
+  fastModel: optionField(Schema.String),
+  fallbackModel: optionField(Schema.String),
+  maxAttempts: optionField(Schema.Number),
+  budgetMillis: optionField(Schema.Number),
+  reasoningEffort: optionField(ReasoningEffort),
+  codeReasoningEffort: optionField(ReasoningEffort),
+  fastReasoningEffort: optionField(ReasoningEffort)
+}) {
+}
+
+export class SettingsError extends Schema.TaggedError()("SettingsError", {
+  message: Schema.String,
+  code: Schema.optionalKey(Schema.Literal("settings.corrupt"))
+}) {
+}
+export const SETTINGS_KEYS = [
+  "fallbackModel",
+  "maxAttempts",
+  "budgetMillis",
+  "reasoningEffort",
+  "codeReasoningEffort",
+  "fastReasoningEffort"
+];
+
+export class SettingsStore extends Context.Service()("@xandreed/core/SettingsStore") {
+}

package/dist/ports/thinking-binding.port.d.ts

@@ -0,0 +1,7 @@
+import { Context } from "effect";
+/**
+ * What the models plugin was configured to tell a model that binds thinking
+ * to the conversation (`thinkingPrefixMismatch`): `drop_block` for adaptive thinking by default;
+ * `provider-default` opts out of the explicit binding field.
+ */
+export declare const CurrentThinkingPrefixMismatch: Context.Reference<"error" | "provider-default" | "drop_block">;

package/dist/ports/thinking-binding.port.js

@@ -0,0 +1,4 @@
+import { Context } from "effect";
+export const CurrentThinkingPrefixMismatch = Context.Reference("@xandreed/plugin-models/CurrentThinkingPrefixMismatch", {
+  defaultValue: () => "drop_block"
+});

package/dist/settings/localSettings.d.ts

@@ -1,3 +1,4 @@
 import { Layer } from "effect";
-import { SettingsStore } from "@xandreed/core";
+import { SettingsStore } from "../ports/settings-store.port.js";
+/** @public */
 export declare const LocalSettingsStoreLive: (cwd: string, home: string) => Layer.Layer<SettingsStore, never, never>;