@xandreed/plugin-models 0.13.0 → 0.14.0

package/dist/plugin.adapter.js

@@ -1,27 +1,65 @@
 import { homedir } from "node:os";
 import { LanguageModel } from "effect/ai";
-import { Effect, Layer, Option, Schema } from "effect";
-import { AuthStore, definePlugin, EngineSettings, ModelCatalog, SessionEnvironment, SettingsError, SettingsStore, UtilityLlm } from "@xandreed/core";
+import { Config as EffectConfig, Context, Effect, Layer, Match, Option, Redacted, Schema } from "effect";
+import { AuthStore, definePlugin, EngineSettings, HarnessError, ModelCatalog, SessionEnvironment, SettingsError, SettingsStore, UtilityLlm } from "@xandreed/core";
+import { CredentialInputs } from "./auth/credential-input.entity.js";
+import { credentialsOf } from "./auth/credential-input.entity.functions.js";
 import { LocalAuthStoreLive } from "./auth/localAuth.js";
+import { MemoryAuthStoreLive } from "./auth/memory-auth.adapter.js";
 import { LanguageModelLive } from "./llm/router.js";
 import { UtilityLlmLive } from "./llm/utilityLlm.js";
 import { ConfiguredModelCatalogLive } from "./llm/modelCatalog.js";
 import { LocalSettingsStoreLive } from "./settings/localSettings.js";
+import { MemorySettingsStoreLive } from "./settings/memory-settings.adapter.js";
+import { HostCredentials } from "./ports/host-credentials.port.js";
 import { CurrentModelEndpoints, ModelEndpoints } from "./ports/model-endpoints.port.js";
-const Config = Schema.Struct({ model: Schema.String, fastModel: Schema.String, fallbackModel: Schema.String, inheritPrevious: Schema.Boolean, endpoints: ModelEndpoints });
+import { ModelsTransport } from "./ports/models-transport.port.js";
+import { ProxyUrlOption } from "./transport/http-proxy.entity.js";
+import { modelsTransportFor } from "./transport/models-transport.adapter.js";
+const Config = Schema.Struct({
+  model: Schema.String,
+  fastModel: Schema.String,
+  fallbackModel: Schema.String,
+  inheritPrevious: Schema.Boolean,
+  endpoints: ModelEndpoints,
+  storage: Schema.Literals(["local", "memory"]),
+  credentials: CredentialInputs,
+  credentialEnv: Schema.Record(Schema.String, Schema.String),
+  proxy: ProxyUrlOption,
+  noProxy: Schema.String
+}).annotate({ messageUnexpectedKey: "not an option of the models plugin" }).check(Schema.makeFilter((config) => config.storage === "memory" || Object.keys(config.credentials).length === 0 && Object.keys(config.credentialEnv).length === 0 ? void 0 : 'credentials and credentialEnv need storage: "memory"')), optional = (value) => value.length === 0 ? Option.none() : Option.some(value), overlaid = (config) => (previous) => new EngineSettings({
+  ...previous,
+  model: Option.orElse(optional(config.model), () => previous.model),
+  fastModel: Option.orElse(optional(config.fastModel), () => previous.fastModel),
+  fallbackModel: Option.orElse(optional(config.fallbackModel), () => previous.fallbackModel)
+}), memoryStores = (config) => Layer.unwrap(Effect.gen(function* () {
+  const fromEnv = yield* Effect.forEach(Object.entries(config.credentialEnv), ([provider, name]) => EffectConfig.option(EffectConfig.Redacted(name)).pipe(Effect.map(Option.map((key) => [provider, { type: "api_key", key: Redacted.value(key) }])))), seed = new Map([...fromEnv.flatMap(Option.toArray), ...credentialsOf(config.credentials)]);
+  return Layer.mergeAll(MemoryAuthStoreLive(seed), MemorySettingsStoreLive(overlaid(config)(new EngineSettings({}))));
+})), readOnly = (what) => () => Effect.fail(new SettingsError({ message: `Edit the models plugin configuration to change ${what}` })), localStores = (config, workspace) => {
+  const home = homedir(), files = Effect.service(SettingsStore).pipe(Effect.provide(LocalSettingsStoreLive(workspace, home))), settings = Layer.effect(SettingsStore, Effect.map(files, (stored) => SettingsStore.of({
+    load: config.inheritPrevious ? Effect.map(stored.load, overlaid(config)) : Effect.succeed(overlaid(config)(new EngineSettings({}))),
+    setRole: readOnly("a model"),
+    set: readOnly("settings")
+  })));
+  return Layer.mergeAll(settings, LocalAuthStoreLive(workspace, home, ".efferent/runtime", config.inheritPrevious ? ".efferent" : void 0));
+}, optionError = (message) => new HarnessError({ code: "config.options", plugin: "@xandreed/plugin-models", message }), transportLayer = (config) => Effect.flatMap(Effect.serviceOption(ModelsTransport), Option.match({
+  onSome: (host) => Redacted.isRedacted(config.proxy) || config.proxy.length > 0 || config.noProxy.length > 0 ? Effect.fail(optionError("the host provides ModelsTransport, so the proxy and noProxy options would not apply: give the proxy to the host's transport")) : Effect.succeed(Layer.succeed(ModelsTransport, host)),
+  onNone: () => Effect.succeed(Layer.effectContext(modelsTransportFor({ proxy: config.proxy, noProxy: config.noProxy }).pipe(Effect.map(Option.match({
+    onNone: () => Context.empty(),
+    onSome: (transport) => Context.make(ModelsTransport, transport)
+  })), Effect.mapError((error) => optionError(error.message)))))
+}));
 export const modelsPlugin = definePlugin({
   id: "@xandreed/plugin-models",
-  version: "0.13.0",
+  version: "0.14.0",
+  scope: "runtime",
   config: Config,
-  defaults: { model: "", fastModel: "", fallbackModel: "", inheritPrevious: !0, endpoints: {} },
+  defaults: { model: "", fastModel: "", fallbackModel: "", inheritPrevious: !0, endpoints: {}, storage: "local", credentials: {}, credentialEnv: {}, proxy: "", noProxy: "" },
   requires: [SessionEnvironment],
+  optional: [HostCredentials, ModelsTransport],
   provides: [LanguageModel.LanguageModel, UtilityLlm, AuthStore, SettingsStore, ModelCatalog],
   layer: (config) => Layer.unwrap(Effect.gen(function* () {
-    const { workspace } = yield* SessionEnvironment, previous = config.inheritPrevious ? yield* SettingsStore.pipe(Effect.flatMap((settings) => settings.load), Effect.provide(LocalSettingsStoreLive(workspace, homedir()))) : new EngineSettings({}), optional = (value) => value.length === 0 ? Option.none() : Option.some(value), settings = Layer.succeed(SettingsStore, {
-      load: Effect.succeed(new EngineSettings({ ...previous, model: Option.orElse(optional(config.model), () => previous.model), fastModel: Option.orElse(optional(config.fastModel), () => previous.fastModel), fallbackModel: Option.orElse(optional(config.fallbackModel), () => previous.fallbackModel) })),
-      setRole: () => Effect.fail(new SettingsError({ message: "Edit the models plugin configuration to change a model" })),
-      set: () => Effect.fail(new SettingsError({ message: "Edit the models plugin configuration to change settings" }))
-    }), base = Layer.mergeAll(settings, LocalAuthStoreLive(workspace, homedir(), ".efferent/runtime", config.inheritPrevious ? ".efferent" : void 0), Layer.succeed(CurrentModelEndpoints, config.endpoints));
+    const { workspace } = yield* SessionEnvironment, host = yield* Effect.serviceOption(HostCredentials), stores = yield* Match.value(config.storage).pipe(Match.when("memory", () => Effect.succeed(memoryStores(config))), Match.when("local", () => Option.isSome(host) ? Effect.fail(optionError('the host provides HostCredentials, which needs storage: "memory"')) : Effect.succeed(localStores(config, workspace))), Match.exhaustive), transport = yield* transportLayer(config), base = Layer.mergeAll(stores, Layer.succeed(CurrentModelEndpoints, config.endpoints)).pipe(Layer.provideMerge(transport));
     return Layer.mergeAll(LanguageModelLive, UtilityLlmLive, ConfiguredModelCatalogLive).pipe(Layer.provideMerge(base));
   }))
 });

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

@@ -0,0 +1,21 @@
+import { Context } from "effect";
+import type { Effect, Option } from "effect";
+import type { AuthError, ProviderId } from "@xandreed/core";
+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-endpoints.port.d.ts

@@ -5,28 +5,41 @@ import { Context, Schema } from "effect";
  * 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.
+ * An endpoint with its own key (`apiKey`, or a set `apiKeyEnv`) never reads
+ * the AuthStore; an empty one (`apiKey: ""`, or a variable set to "") sends
+ * no key. A host's code passes `apiKey` as a `Redacted` string so it
+ * prints as `<redacted>` in errors and graph fingerprints; JSON
+ * configuration names an environment variable in `apiKeyEnv` instead.
  * `standardOnly` (default true) sends only standard chat-completions fields.
+ * `images` (default false) says its models read images: a user's images are
+ * then sent as `image_url` parts, and a tool result's in one user message
+ * after the tool results; without it they are label lines.
+ * The endpoint's usage is read in full: cache reads and writes from
+ * `prompt_tokens_details`, reasoning from `completion_tokens_details`.
  */
 export declare const ModelEndpoint: Schema.Struct<{
     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 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 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. */
 export declare const CurrentModelEndpoints: Context.Reference<{
     readonly [x: string]: {
         readonly url: string;
-        readonly apiKey?: string;
+        readonly images?: boolean;
+        readonly apiKey?: string | import("effect/Redacted").Redacted<string>;
         readonly apiKeyEnv?: string;
         readonly standardOnly?: boolean;
     };

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

@@ -1,9 +1,13 @@
 import { Context, Schema } from "effect";
 export const ModelEndpoint = Schema.Struct({
   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", {
+  standardOnly: Schema.optionalKey(Schema.Boolean),
+  images: Schema.optionalKey(Schema.Boolean)
+}).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/models-transport.port.d.ts

@@ -0,0 +1,46 @@
+import { Context } from "effect";
+import type { Effect, Option, 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.
+ */
+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 {
+}
+export {};

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

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

package/dist/settings/localSettings.js

@@ -1,33 +1,12 @@
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { Effect, Layer, Option } from "effect";
-import { asJsonRecord, EngineSettings, parseJsonWarn, parseModelSelection, SettingsError, SettingsStore } from "@xandreed/core";
+import { asJsonRecord, parseJsonWarn, SettingsError, SettingsStore } from "@xandreed/core";
+import { coerceSettingValue, ROLE_FIELDS, roleSelection, settingsFromRecord } from "./settings-value.entity.functions.js";
 const configPaths = (cwd, home) => [
   join(home, ".efferent", "config.json"),
   join(cwd, ".efferent", "config.json")
-], readConfig = (path) => Effect.tryPromise({ try: () => readFile(path, "utf-8"), catch: () => "missing" }).pipe(Effect.flatMap((text) => parseJsonWarn(text, path)), Effect.map(asJsonRecord), Effect.orElseSucceed(() => ({}))), asString = (value) => typeof value === "string" && value.length > 0 ? Option.some(value) : Option.none(), asBoolean = (value) => typeof value === "boolean" ? Option.some(value) : Option.none(), asNumber = (value) => typeof value === "number" && Number.isFinite(value) ? Option.some(value) : Option.none(), asReasoningEffort = (value) => value === "none" || value === "low" || value === "medium" || value === "high" || value === "xhigh" || value === "max" ? Option.some(value) : Option.none(), coerceSettingValue = (key, raw) => {
-  if (key === "fallbackModel")
-    return Option.match(parseModelSelection(raw), {
-      onNone: () => Effect.fail(new SettingsError({
-        message: `fallbackModel must be "<provider>:<modelId>" \u2014 got "${raw}"`
-      })),
-      onSome: () => Effect.succeed(raw)
-    });
-  if (key === "sandbox" || key === "viMode") {
-    if (raw === "true" || raw === "on")
-      return Effect.succeed(!0);
-    if (raw === "false" || raw === "off")
-      return Effect.succeed(!1);
-    return Effect.fail(new SettingsError({ message: `${key} must be true/false \u2014 got "${raw}"` }));
-  }
-  if (key === "reasoningEffort" || key === "codeReasoningEffort" || key === "fastReasoningEffort")
-    return Option.match(asReasoningEffort(raw), {
-      onNone: () => Effect.fail(new SettingsError({ message: `reasoningEffort is not supported: "${raw}"` })),
-      onSome: Effect.succeed
-    });
-  const parsed = Number(raw);
-  return Number.isInteger(parsed) && parsed >= 1 ? Effect.succeed(parsed) : Effect.fail(new SettingsError({ message: `${key} must be a positive integer \u2014 got "${raw}"` }));
-}, writeKey = (cwd, key, value) => Effect.gen(function* () {
+], readConfig = (path) => Effect.tryPromise({ try: () => readFile(path, "utf-8"), catch: () => "missing" }).pipe(Effect.flatMap((text) => parseJsonWarn(text, path)), Effect.map(asJsonRecord), Effect.orElseSucceed(() => ({}))), writeKey = (cwd, key, value) => Effect.gen(function* () {
   const path = join(cwd, ".efferent", "config.json"), current = yield* readConfig(path), next = Option.match(value, {
     onNone: () => Object.fromEntries(Object.entries(current).filter(([k]) => k !== key)),
     onSome: (v) => ({ ...current, [key]: v })
@@ -35,33 +14,14 @@ const configPaths = (cwd, home) => [
   yield* writeConfigAtomic(path, next);
 });
 export const LocalSettingsStoreLive = (cwd, home) => Layer.succeed(SettingsStore, {
-  load: Effect.gen(function* () {
-    const merged = (yield* Effect.forEach(configPaths(cwd, home), readConfig)).reduce((acc, c) => ({ ...acc, ...c }), {});
-    return new EngineSettings({
-      model: asString(merged.model),
-      codeModel: asString(merged.codeModel),
-      fastModel: asString(merged.fastModel),
-      fallbackModel: asString(merged.fallbackModel),
-      sandbox: asBoolean(merged.sandbox),
-      viMode: asBoolean(merged.viMode),
-      maxAttempts: asNumber(merged.maxAttempts),
-      budgetMillis: asNumber(merged.budgetMillis),
-      reasoningEffort: Option.orElse(asReasoningEffort(merged.reasoningEffort), () => asReasoningEffort(merged.openAiReasoningEffort)),
-      codeReasoningEffort: asReasoningEffort(merged.codeReasoningEffort),
-      fastReasoningEffort: asReasoningEffort(merged.fastReasoningEffort)
-    });
-  }),
-  setRole: (role, selection) => writeKey(cwd, ROLE_KEYS[role], selection),
+  load: Effect.forEach(configPaths(cwd, home), readConfig).pipe(Effect.map((configs) => settingsFromRecord(configs.reduce((acc, c) => ({ ...acc, ...c }), {})))),
+  setRole: (role, selection) => roleSelection(role, selection).pipe(Effect.flatMap((checked) => writeKey(cwd, ROLE_FIELDS[role], checked))),
   set: (key, value) => Option.match(value, {
     onNone: () => writeKey(cwd, key, Option.none()),
     onSome: (raw) => coerceSettingValue(key, raw).pipe(Effect.flatMap((coerced) => writeKey(cwd, key, Option.some(coerced))))
   })
 });
-const ROLE_KEYS = {
-  general: "model",
-  code: "codeModel",
-  fast: "fastModel"
-}, writeConfigAtomic = (path, config) => Effect.tryPromise({
+const writeConfigAtomic = (path, config) => Effect.tryPromise({
   try: async () => {
     await mkdir(dirname(path), { recursive: !0 });
     const tmp = `${path}.tmp-${process.pid}`;

package/dist/settings/memory-settings.adapter.d.ts

@@ -0,0 +1,10 @@
+import { Layer } from "effect";
+import { EngineSettings, SettingsStore } from "@xandreed/core";
+/**
+ * `MemorySettingsStoreLive(initial)` — a SettingsStore that never touches
+ * disk: one writable value for the layer's lifetime, starting at `initial`.
+ * `setRole` and `set` check their value the way the file store does
+ * (a `"<provider>:<modelId>"` selection; each key's string form) and refuse
+ * one that does not parse, leaving the settings as they were.
+ */
+export declare const MemorySettingsStoreLive: (initial?: EngineSettings) => Layer.Layer<SettingsStore>;

package/dist/settings/memory-settings.adapter.js

@@ -0,0 +1,11 @@
+import { Effect, Layer, SynchronizedRef } from "effect";
+import { EngineSettings, SettingsStore } from "@xandreed/core";
+import { applyRole, applySetting } from "./settings-value.entity.functions.js";
+export const MemorySettingsStoreLive = (initial = new EngineSettings({})) => Layer.effect(SettingsStore, Effect.gen(function* () {
+  const state = yield* SynchronizedRef.make(initial);
+  return SettingsStore.of({
+    load: SynchronizedRef.get(state),
+    setRole: (role, selection) => SynchronizedRef.updateEffect(state, (settings) => applyRole(settings, role, selection)),
+    set: (key, value) => SynchronizedRef.updateEffect(state, (settings) => applySetting(settings, key, value))
+  });
+}));

package/dist/settings/memory-settings.adapter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/settings/settings-value.entity.d.ts

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+/** A settings value as a config file holds it: a selection or other text, a switch, a count. */
+export declare const SettingValue: Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.Number]>;
+export type SettingValue = typeof SettingValue.Type;
+/** The settings field each model role is kept under. */
+export declare const RoleField: Schema.Literals<readonly ["model", "codeModel", "fastModel"]>;
+export type RoleField = typeof RoleField.Type;

package/dist/settings/settings-value.entity.functions.d.ts

@@ -0,0 +1,29 @@
+import { Effect, Option } from "effect";
+import { EngineSettings, SettingsError } from "@xandreed/core";
+import type { ModelRole, SettingsKey } from "@xandreed/core";
+import type { RoleField, SettingValue } from "./settings-value.entity.js";
+/**
+ * The settings vocabulary every SettingsStore of this package shares: how a
+ * config record reads as `EngineSettings`, how a value's string form (what
+ * `set` receives: "true", "3", "provider:model") is checked and coerced, and
+ * how one key or role changes a settings value.
+ */
+/** The field each model role is kept under. */
+export declare const ROLE_FIELDS: Readonly<Record<ModelRole, RoleField>>;
+/** Settings from a config record: values of the wrong type read as unset; the legacy `openAiReasoningEffort` key backs `reasoningEffort`. */
+export declare const settingsFromRecord: (record: Readonly<Record<string, unknown>>) => EngineSettings;
+/** Settings as a config record: the set fields only. */
+export declare const recordOfSettings: (settings: EngineSettings) => Readonly<Record<string, SettingValue>>;
+/**
+ * One key's value from its string form, checked: a selection must be
+ * `"<provider>:<modelId>"`, a switch true/on/false/off, an effort one the
+ * models accept, a count a positive integer. A value that does not parse is
+ * refused, not written and then ignored on load.
+ */
+export declare const coerceSettingValue: (key: SettingsKey, raw: string) => Effect.Effect<SettingValue, SettingsError>;
+/** A role's selection, checked: `None` clears the role; a value must be `"<provider>:<modelId>"`. */
+export declare const roleSelection: (role: ModelRole, selection: Option.Option<string>) => Effect.Effect<Option.Option<string>, SettingsError>;
+/** `settings` with one key set from its string form (checked, as `set` takes it), or cleared with `None`. */
+export declare const applySetting: (settings: EngineSettings, key: SettingsKey, value: Option.Option<string>) => Effect.Effect<EngineSettings, SettingsError>;
+/** `settings` with one role's selection set (checked, as `setRole` takes it), or cleared with `None`. */
+export declare const applyRole: (settings: EngineSettings, role: ModelRole, selection: Option.Option<string>) => Effect.Effect<EngineSettings, SettingsError>;

package/dist/settings/settings-value.entity.functions.js

@@ -0,0 +1,43 @@
+import { Effect, Match, Option } from "effect";
+import { EngineSettings, parseModelSelection, SETTINGS_KEYS, SettingsError } from "@xandreed/core";
+export const ROLE_FIELDS = {
+  general: "model",
+  code: "codeModel",
+  fast: "fastModel"
+};
+const FIELDS = ["model", "codeModel", "fastModel", ...SETTINGS_KEYS], asString = (value) => typeof value === "string" && value.length > 0 ? Option.some(value) : Option.none(), asBoolean = (value) => typeof value === "boolean" ? Option.some(value) : Option.none(), asNumber = (value) => typeof value === "number" && Number.isFinite(value) ? Option.some(value) : Option.none(), asReasoningEffort = (value) => value === "none" || value === "low" || value === "medium" || value === "high" || value === "xhigh" || value === "max" ? Option.some(value) : Option.none();
+export const settingsFromRecord = (record) => new EngineSettings({
+  model: asString(record.model),
+  codeModel: asString(record.codeModel),
+  fastModel: asString(record.fastModel),
+  fallbackModel: asString(record.fallbackModel),
+  sandbox: asBoolean(record.sandbox),
+  viMode: asBoolean(record.viMode),
+  maxAttempts: asNumber(record.maxAttempts),
+  budgetMillis: asNumber(record.budgetMillis),
+  reasoningEffort: Option.orElse(asReasoningEffort(record.reasoningEffort), () => asReasoningEffort(record.openAiReasoningEffort)),
+  codeReasoningEffort: asReasoningEffort(record.codeReasoningEffort),
+  fastReasoningEffort: asReasoningEffort(record.fastReasoningEffort)
+}), recordOfSettings = (settings) => Object.fromEntries(FIELDS.flatMap((field) => Option.match(fieldOf(settings, field), {
+  onNone: () => [],
+  onSome: (value) => [[field, value]]
+})));
+const fieldOf = (settings, field) => settings[field], refuse = (message) => Effect.fail(new SettingsError({ message }));
+export const coerceSettingValue = (key, raw) => Match.value(key).pipe(Match.when("fallbackModel", () => Option.match(parseModelSelection(raw), {
+  onNone: () => refuse(`fallbackModel must be "<provider>:<modelId>" \u2014 got "${raw}"`),
+  onSome: () => Effect.succeed(raw)
+})), Match.whenOr("sandbox", "viMode", (flag) => raw === "true" || raw === "on" ? Effect.succeed(!0) : raw === "false" || raw === "off" ? Effect.succeed(!1) : refuse(`${flag} must be true/false \u2014 got "${raw}"`)), Match.whenOr("reasoningEffort", "codeReasoningEffort", "fastReasoningEffort", (effort) => Option.match(asReasoningEffort(raw), {
+  onNone: () => refuse(`${effort} is not supported: "${raw}"`),
+  onSome: (value) => Effect.succeed(value)
+})), Match.whenOr("maxAttempts", "budgetMillis", (count) => Number.isInteger(Number(raw)) && Number(raw) >= 1 ? Effect.succeed(Number(raw)) : refuse(`${count} must be a positive integer \u2014 got "${raw}"`)), Match.exhaustive), roleSelection = (role, selection) => Option.match(selection, {
+  onNone: () => Effect.succeed(Option.none()),
+  onSome: (raw) => Option.isSome(parseModelSelection(raw)) ? Effect.succeed(Option.some(raw)) : refuse(`the ${role} model must be "<provider>:<modelId>" \u2014 got "${raw}"`)
+});
+const withField = (settings, field, value) => {
+  const others = Object.fromEntries(Object.entries(recordOfSettings(settings)).filter(([key]) => key !== field));
+  return settingsFromRecord(Option.match(value, { onNone: () => others, onSome: (set) => ({ ...others, [field]: set }) }));
+};
+export const applySetting = (settings, key, value) => Option.match(value, {
+  onNone: () => Effect.succeed(withField(settings, key, Option.none())),
+  onSome: (raw) => coerceSettingValue(key, raw).pipe(Effect.map((coerced) => withField(settings, key, Option.some(coerced))))
+}), applyRole = (settings, role, selection) => roleSelection(role, selection).pipe(Effect.map((checked) => withField(settings, ROLE_FIELDS[role], checked)));

package/dist/settings/settings-value.entity.functions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/settings/settings-value.entity.js

@@ -0,0 +1,2 @@
+import { Schema } from "effect";
+export const SettingValue = Schema.Union([Schema.String, Schema.Boolean, Schema.Number]), RoleField = Schema.Literals(["model", "codeModel", "fastModel"]);

package/dist/transport/http-proxy.entity.d.ts

@@ -0,0 +1,90 @@
+import { Schema } from "effect";
+/** A proxy URL as an option takes it: a string, or a `Redacted` one when it carries credentials. */
+export declare const ProxyUrlOption: Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>;
+export type ProxyUrlOption = typeof ProxyUrlOption.Type;
+/**
+ * The proxy a host gives the models plugin, as its `proxy` and `noProxy`
+ * options. `proxy` is one URL for every model and OAuth call (`http://` or
+ * `https://`; a value without a scheme reads as `http://`); it may carry
+ * credentials (`http://user:pass@proxy:8080`), so a host's code can pass it
+ * `Redacted`. Empty or absent, the environment's `https_proxy` /
+ * `HTTPS_PROXY` and `http_proxy` / `HTTP_PROXY` apply. `noProxy` lists the
+ * hosts that go direct, in NO_PROXY syntax, added to the environment's
+ * `no_proxy` / `NO_PROXY`; `"*"` turns the proxy off.
+ */
+export declare const HttpProxyOptions: Schema.Struct<{
+    readonly proxy: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
+    readonly noProxy: Schema.optionalKey<Schema.String>;
+}>;
+export type HttpProxyOptions = typeof HttpProxyOptions.Type;
+/**
+ * The proxy variables of the environment, as read (an empty value counts as
+ * unset). Lower case is read before upper case, as undici (Node's
+ * environment proxy) and curl read them. `ALL_PROXY` is not read: SOCKS
+ * proxies are not supported.
+ */
+export declare const ProxyEnvironment: Schema.Struct<{
+    readonly https_proxy: Schema.optionalKey<Schema.String>;
+    readonly HTTPS_PROXY: Schema.optionalKey<Schema.String>;
+    readonly http_proxy: Schema.optionalKey<Schema.String>;
+    readonly HTTP_PROXY: Schema.optionalKey<Schema.String>;
+    readonly no_proxy: Schema.optionalKey<Schema.String>;
+    readonly NO_PROXY: Schema.optionalKey<Schema.String>;
+}>;
+export type ProxyEnvironment = typeof ProxyEnvironment.Type;
+/** The environment variables a `ProxyEnvironment` is read from. */
+export declare const PROXY_VARIABLES: readonly ["https_proxy", "HTTPS_PROXY", "http_proxy", "HTTP_PROXY", "no_proxy", "NO_PROXY"];
+/**
+ * One NO_PROXY entry: every host (`*`); a host name and its subdomains
+ * (`example.com`, `.example.com` and `*.example.com` alike); or an IP
+ * address, exact (`10.1.2.3`, `::1`, `[::1]`) or a range (`10.0.0.0/8`,
+ * `fd00::/8`, as `prefix` leading bits). A name or an exact address may
+ * carry a port (`example.com:8443`, `[::1]:8080`), which then must match.
+ */
+export declare const NoProxyRule: Schema.Union<readonly [Schema.TaggedStruct<"Everything", {}>, Schema.TaggedStruct<"Domain", {
+    readonly name: Schema.String;
+    readonly port: Schema.Option<Schema.Int>;
+}>, Schema.TaggedStruct<"Address", {
+    readonly bytes: Schema.$Array<Schema.Int>;
+    readonly prefix: Schema.Int;
+    readonly port: Schema.Option<Schema.Int>;
+}>]>;
+export type NoProxyRule = typeof NoProxyRule.Type;
+declare const ProxyConfig_base: Schema.Class<ProxyConfig, Schema.Struct<{
+    readonly https: Schema.Option<Schema.Redacted<Schema.String>>;
+    readonly http: Schema.Option<Schema.Redacted<Schema.String>>;
+    readonly noProxy: Schema.$Array<Schema.Union<readonly [Schema.TaggedStruct<"Everything", {}>, Schema.TaggedStruct<"Domain", {
+        readonly name: Schema.String;
+        readonly port: Schema.Option<Schema.Int>;
+    }>, Schema.TaggedStruct<"Address", {
+        readonly bytes: Schema.$Array<Schema.Int>;
+        readonly prefix: Schema.Int;
+        readonly port: Schema.Option<Schema.Int>;
+    }>]>>;
+}>, {}>;
+/**
+ * A resolved proxy setting: the proxy for `https:` (and `wss:`) targets,
+ * the one for `http:` (and `ws:`) targets, and the hosts that go direct.
+ * Proxy URLs stay `Redacted`, so a printed setting never shows credentials.
+ * Loopback hosts always go direct.
+ */
+export declare class ProxyConfig extends ProxyConfig_base {
+}
+declare const ProxyInvalid_base: Schema.Class<ProxyInvalid, Schema.TaggedStruct<"ProxyInvalid", {
+    readonly source: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** A proxy URL that cannot be used: not a URL, or not `http://` / `https://`. `source` names where it came from. */
+export declare class ProxyInvalid extends ProxyInvalid_base {
+}
+declare const ProxyUnsupported_base: Schema.Class<ProxyUnsupported, Schema.TaggedStruct<"ProxyUnsupported", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** A proxy applies, but this runtime cannot send the call through it: the call is refused rather than sent direct. */
+export declare class ProxyUnsupported extends ProxyUnsupported_base {
+}
+/** The first Bun whose native `WebSocket` sends through its `proxy` option (1.3.0 to 1.3.5 connect directly). */
+export declare const BUN_WEBSOCKET_PROXY_VERSION = "1.3.6";
+/** The first Node whose `https.Agent` tunnels through its `proxyEnv` option (earlier ones connect directly). */
+export declare const NODE_WEBSOCKET_PROXY_VERSION = "24.5.0";
+export {};

package/dist/transport/http-proxy.entity.functions.d.ts

@@ -0,0 +1,51 @@
+import { Option, Redacted, Result } from "effect";
+import { ProxyConfig, ProxyInvalid } from "./http-proxy.entity.js";
+import type { HttpProxyOptions, NoProxyRule, ProxyEnvironment } from "./http-proxy.entity.js";
+/**
+ * Credentials in the URLs of `text` (`scheme://user:pass@host`) replaced by
+ * `<redacted>`, for error messages that may quote a proxy URL.
+ */
+export declare const redactCredentials: (text: string) => string;
+/** A proxy URL as a message may show it: its scheme and host, its credentials (if any) as `<redacted>`. */
+export declare const displayProxy: (url: Redacted.Redacted<string>) => string;
+/**
+ * One proxy URL, checked: `None` when blank; a value without a scheme
+ * (`proxy.corp:8080`) reads as `http://`; anything that is not an `http://`
+ * or `https://` URL with a host fails with `ProxyInvalid` naming `source`,
+ * credentials redacted.
+ */
+export declare const proxyUrl: (raw: string, source: string) => Result.Result<Option.Option<Redacted.Redacted<string>>, ProxyInvalid>;
+/** The IPv4 address `text` spells, as its 4 bytes. */
+export declare const parseIpv4: (text: string) => Option.Option<ReadonlyArray<number>>;
+/** The IPv6 address `text` spells (brackets and a zone id allowed), as its 16 bytes. */
+export declare const parseIpv6: (text: string) => Option.Option<ReadonlyArray<number>>;
+/** A host is loopback: `localhost` (and its subdomains), `127.0.0.0/8`, `::1`, or IPv4 loopback mapped into IPv6. */
+export declare const isLoopback: (hostname: string) => boolean;
+/** A NO_PROXY value (entries separated by commas or white space), parsed. */
+export declare const parseNoProxy: (value: string) => ReadonlyArray<NoProxyRule>;
+/** Whether a NO_PROXY rule sends `target` direct. */
+export declare const bypassesProxy: (rules: ReadonlyArray<NoProxyRule>, target: URL) => boolean;
+/**
+ * The proxy settings of the models plugin's options over the environment's:
+ * an explicit `proxy` serves every target; otherwise `https_proxy` (then
+ * `HTTPS_PROXY`) serves `https:` targets, `http_proxy` (then `HTTP_PROXY`)
+ * `http:` ones, and an `https:` target falls back to the `http:` proxy, as
+ * undici's environment proxy (Node's, under `NODE_USE_ENV_PROXY`) does. The
+ * direct hosts are `no_proxy` (then `NO_PROXY`) and the `noProxy` option
+ * together; with `*` among them the environment's proxy variables are not
+ * read at all. Lower case comes first, as undici and curl read them. A proxy
+ * URL that cannot be used fails with `ProxyInvalid`.
+ */
+export declare const resolveProxy: (options: HttpProxyOptions, env: ProxyEnvironment) => Result.Result<ProxyConfig, ProxyInvalid>;
+/** Whether any target can go through a proxy. */
+export declare const usesProxy: (config: ProxyConfig) => boolean;
+/** Whether the setting turns the proxy off for every host (`*` in `noProxy` or `NO_PROXY`). */
+export declare const turnsProxyOff: (config: ProxyConfig) => boolean;
+/**
+ * The proxy a request to `target` goes through, or `None` for direct:
+ * loopback hosts and the `noProxy` hosts go direct; `https:` and `wss:`
+ * targets use the https proxy, `http:` and `ws:` ones the http proxy.
+ */
+export declare const proxyFor: (target: URL, config: ProxyConfig) => Option.Option<Redacted.Redacted<string>>;
+/** Whether a runtime `version` (`24.16.0`, `1.3.6`) is at least `minimum`; an unreadable one is not. */
+export declare const atLeastVersion: (version: string, minimum: string) => boolean;