@xandreed/plugin-models 0.14.0 → 0.15.0

package/dist/settings/settings-store.conformance.js

@@ -0,0 +1,100 @@
+import { Effect, Option } from "effect";
+import { canonicalJson, harnessCodeOf, parseModelSelection } from "@xandreed/core";
+import { check, ConformanceFailure } from "@xandreed/core/conformance";
+import { randomUuid } from "@xandreed/core/internal";
+import { SETTINGS_KEYS } from "../ports/settings-store.port.js";
+const fail = (id, message) => Effect.fail(new ConformanceFailure({ check: id, message })), expect = (id, holds, message) => holds ? Effect.void : fail(id, message), ROLE_FIELDS = { general: "model", code: "codeModel", fast: "fastModel" }, ROLES = ["general", "code", "fast"], FIELDS = ["model", "codeModel", "fastModel", ...SETTINGS_KEYS], fieldOf = (settings, field) => settings[field], valueOf = (settings, field) => Option.map(fieldOf(settings, field), String), snapshot = (settings) => canonicalJson(Object.fromEntries(FIELDS.map((field) => [field, Option.getOrNull(valueOf(settings, field))]))), others = (settings, except) => canonicalJson(Object.fromEntries(FIELDS.filter((field) => field !== except).map((field) => [field, Option.getOrNull(valueOf(settings, field))]))), selection = (label) => Effect.map(randomUuid, (id) => `conformance:${label}-${id}`), SELECTIONS = new Set(["model", "codeModel", "fastModel", "fallbackModel"]), COUNTS = new Set(["maxAttempts", "budgetMillis"]), restorable = (field, value) => SELECTIONS.has(field) ? Option.isSome(parseModelSelection(value)) : COUNTS.has(field) ? Number.isInteger(Number(value)) && Number(value) >= 1 : !0, restoring = (store, id, field, write) => (body) => store.load.pipe(Effect.flatMap((before) => Option.match(Option.filter(valueOf(before, field), (value) => !restorable(field, value)), {
+  onSome: (value) => fail(id, `the store holds ${field} "${value}", which a conforming store refuses to write, so the kit could not put it back; it changed nothing. Correct the value, then run the kit`),
+  onNone: () => body.pipe(Effect.ensuring(store.load.pipe(Effect.flatMap((after) => Option.getOrNull(valueOf(after, field)) === Option.getOrNull(valueOf(before, field)) ? Effect.void : write(valueOf(before, field))), Effect.ignore({ log: "Warn", message: `the kit could not put back ${field}` }))))
+}))), restoringRole = (store, id, role) => restoring(store, id, ROLE_FIELDS[role], (value) => store.setRole(role, value)), restoringKey = (store, id, key) => restoring(store, id, key, (value) => store.set(key, value)), refused = (store, id, what, write) => Effect.gen(function* () {
+  const before = snapshot(yield* store.load), result = yield* Effect.result(write);
+  if (result._tag === "Success")
+    return yield* fail(id, `${what} was accepted`);
+  const tag = typeof result.failure === "object" && result.failure !== null && "_tag" in result.failure ? String(result.failure._tag) : "an error";
+  yield* expect(id, tag === "SettingsError", `${what} failed with ${tag}, not a SettingsError`);
+  yield* expect(id, snapshot(yield* store.load) === before, `${what} changed the settings`);
+}), CANONICAL = [
+  { key: "maxAttempts", text: "3", reads: 3 },
+  { key: "budgetMillis", text: "60000", reads: 60000 },
+  { key: "reasoningEffort", text: "high", reads: "high" }
+], CLEARED = [
+  { key: "maxAttempts", texts: ["4", "5"] },
+  { key: "budgetMillis", texts: ["1000", "2000"] },
+  { key: "reasoningEffort", texts: ["low", "medium"] }
+], BAD = [
+  { key: "fallbackModel", text: "not-a-selection" },
+  { key: "maxAttempts", text: "0" },
+  { key: "maxAttempts", text: "two" },
+  { key: "budgetMillis", text: "1.5" },
+  { key: "reasoningEffort", text: "extreme" }
+], corrupted = (what, effect) => Effect.result(effect).pipe(Effect.flatMap((result) => {
+  if (result._tag === "Success")
+    return fail("corrupt", `${what} succeeded on a store whose backing data cannot be read`);
+  const error = result.failure, tag = typeof error === "object" && error !== null && "_tag" in error ? String(error._tag) : "an error", code = Option.getOrElse(harnessCodeOf(error), () => "no code");
+  return expect("corrupt", tag === "SettingsError" && code === "settings.corrupt", `${what} failed with ${tag} (${code}), not a SettingsError of code settings.corrupt`);
+})), corruptCheck = (store, writable, corrupt) => check("a store whose backing data cannot be read fails load and every write with a SettingsError of code settings.corrupt, never reads it as defaults", "corrupt", () => {
+  const body = Effect.gen(function* () {
+    const before = snapshot(yield* store.load);
+    yield* Effect.scoped(Effect.gen(function* () {
+      yield* corrupt;
+      yield* corrupted("load", store.load);
+      yield* writable ? Effect.all([
+        selection("corrupt").pipe(Effect.flatMap((value) => corrupted("setRole", store.setRole("general", Option.some(value))))),
+        corrupted("set", store.set("maxAttempts", Option.some("3")))
+      ], { concurrency: 1, discard: !0 }) : Effect.void;
+    }));
+    yield* expect("corrupt", snapshot(yield* store.load) === before, "once the backing data is repaired, the store does not read what it held before");
+  });
+  return writable ? body.pipe(restoringRole(store, "corrupt", "general"), restoringKey(store, "corrupt", "maxAttempts")) : body;
+});
+export const settingsStoreConformance = (store, options) => [
+  check("load is stable: two loads with no write between them agree", "load", () => Effect.gen(function* () {
+    const first = snapshot(yield* store.load);
+    yield* expect("load", snapshot(yield* store.load) === first, "two loads disagree");
+  })),
+  ...options.writable ? writableChecks(store) : readOnlyChecks(store),
+  ...Option.match(Option.fromNullishOr(options.corrupt), { onNone: () => [], onSome: (corrupt) => [corruptCheck(store, options.writable, corrupt)] })
+];
+const writableChecks = (store) => [
+  check("each role reads back what setRole wrote, and clearing it returns the value before the set", "role", () => Effect.forEach(ROLES, (role) => Effect.gen(function* () {
+    const field = ROLE_FIELDS[role];
+    yield* store.setRole(role, Option.none());
+    const base = yield* store.load, value = yield* selection(role);
+    yield* store.setRole(role, Option.some(value));
+    const set = yield* store.load;
+    yield* expect("role", Option.getOrUndefined(valueOf(set, field)) === value, `the ${role} role reads ${Option.getOrElse(valueOf(set, field), () => "nothing")}, not what was set`);
+    yield* expect("role", others(set, field) === others(base, field), `setting the ${role} role changed another value`);
+    yield* store.setRole(role, Option.none());
+    yield* expect("role", snapshot(yield* store.load) === snapshot(base), `clearing the ${role} role did not return the value before the set`);
+  }).pipe(restoringRole(store, "role", role)), { concurrency: 1, discard: !0 })),
+  check("set accepts each key's canonical string form and load reads it back typed", "values", () => selection("fallback").pipe(Effect.flatMap((fallback) => Effect.forEach([
+    ...CANONICAL,
+    { key: "fallbackModel", text: fallback, reads: void 0 }
+  ], ({ key, text, reads }) => Effect.gen(function* () {
+    const before = yield* store.load;
+    yield* store.set(key, Option.some(text));
+    const after = yield* store.load, expected = reads ?? text, read = Option.getOrNull(fieldOf(after, key));
+    yield* expect("values", read === expected, `${key} "${text}" reads back as ${JSON.stringify(read)}`);
+    yield* expect("values", others(after, key) === others(before, key), `setting ${key} changed another value`);
+  }).pipe(restoringKey(store, "values", key)), { concurrency: 1, discard: !0 })))),
+  check("None clears a key back to the value before the set", "clear", () => Effect.forEach(CLEARED, ({ key, texts }) => Effect.gen(function* () {
+    yield* store.set(key, Option.none());
+    const base = yield* store.load, text = texts.find((candidate) => Option.getOrNull(valueOf(base, key)) !== candidate) ?? texts[0];
+    yield* store.set(key, Option.some(text));
+    yield* store.set(key, Option.none());
+    yield* expect("clear", snapshot(yield* store.load) === snapshot(base), `clearing ${key} did not return the value before the set`);
+  }).pipe(restoringKey(store, "clear", key)), { concurrency: 1, discard: !0 })),
+  check("set refuses a value that does not parse with a SettingsError and changes nothing", "bad-values", () => Effect.forEach(BAD, ({ key, text }) => refused(store, "bad-values", `${key} "${text}"`, store.set(key, Option.some(text))).pipe(restoringKey(store, "bad-values", key)), { concurrency: 1, discard: !0 })),
+  check('setRole refuses a selection that is not "<provider>:<modelId>" with a SettingsError and changes nothing', "bad-role", () => Effect.forEach(ROLES, (role) => Effect.forEach(["not-a-selection", ":model", "provider:"], (text) => refused(store, "bad-role", `the ${role} role "${text}"`, store.setRole(role, Option.some(text))), { concurrency: 1, discard: !0 }).pipe(restoringRole(store, "bad-role", role)), { concurrency: 1, discard: !0 }))
+], readOnlyChecks = (store) => [
+  check("a read-only store refuses every write with a SettingsError and changes nothing", "read-only", () => Effect.gen(function* () {
+    yield* Effect.forEach(ROLES, (role) => Effect.all([
+      selection(role).pipe(Effect.flatMap((value) => refused(store, "read-only", `setRole ${role}`, store.setRole(role, Option.some(value))))),
+      refused(store, "read-only", `clearing the ${role} role`, store.setRole(role, Option.none()))
+    ], { concurrency: 1 }), { concurrency: 1, discard: !0 });
+    yield* Effect.forEach(CANONICAL, ({ key, text }) => Effect.all([
+      refused(store, "read-only", `set ${key}`, store.set(key, Option.some(text))),
+      refused(store, "read-only", `clearing ${key}`, store.set(key, Option.none()))
+    ], { concurrency: 1 }), { concurrency: 1, discard: !0 });
+  }))
+];

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

@@ -1,7 +1,15 @@
 import { Schema } from "effect";
-/** A settings value as a config file holds it: a selection or other text, a switch, a count. */
+/**
+ * A settings value as a config file holds it: a selection or other text, a switch, a count.
+ *
+ * @public
+ */
 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. */
+/**
+ * The settings field each model role is kept under.
+ *
+ * @public
+ */
 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

@@ -1,6 +1,6 @@
 import { Effect, Option } from "effect";
-import { EngineSettings, SettingsError } from "@xandreed/core";
-import type { ModelRole, SettingsKey } from "@xandreed/core";
+import { EngineSettings, SettingsError } from "../ports/settings-store.port.js";
+import type { ModelRole, SettingsKey } from "../ports/settings-store.port.js";
 import type { RoleField, SettingValue } from "./settings-value.entity.js";
 /**
  * The settings vocabulary every SettingsStore of this package shares: how a
@@ -8,22 +8,44 @@ import type { RoleField, SettingValue } from "./settings-value.entity.js";
  * `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. */
+/**
+ * The field each model role is kept under.
+ *
+ * @public
+ */
 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`. */
+/**
+ * Settings from a config record: values of the wrong type read as unset, keys it does not name are not read; the legacy `openAiReasoningEffort` key backs `reasoningEffort`.
+ *
+ * @public
+ */
 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
+ * `"<provider>:<modelId>"`, 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.
+ *
+ * @public
  */
 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>"`. */
+/**
+ * A role's selection, checked: `None` clears the role; a value must be `"<provider>:<modelId>"`.
+ *
+ * @public
+ */
 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`. */
+/**
+ * `settings` with one key set from its string form (checked, as `set` takes it), or cleared with `None`.
+ *
+ * @public
+ */
 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`. */
+/**
+ * `settings` with one role's selection set (checked, as `setRole` takes it), or cleared with `None`.
+ *
+ * @public
+ */
 export declare const applyRole: (settings: EngineSettings, role: ModelRole, selection: Option.Option<string>) => Effect.Effect<EngineSettings, SettingsError>;

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

@@ -1,18 +1,17 @@
-import { Effect, Match, Option } from "effect";
-import { EngineSettings, parseModelSelection, SETTINGS_KEYS, SettingsError } from "@xandreed/core";
+import { Effect, Match, Option, Schema } from "effect";
+import { parseModelSelection, ReasoningEffort } from "@xandreed/core";
+import { EngineSettings, SETTINGS_KEYS, SettingsError } from "../ports/settings-store.port.js";
 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();
+const FIELDS = ["model", "codeModel", "fastModel", ...SETTINGS_KEYS], asString = Schema.decodeUnknownOption(Schema.NonEmptyString), asNumber = Schema.decodeUnknownOption(Schema.Finite), asReasoningEffort = Schema.decodeUnknownOption(ReasoningEffort);
 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)),
@@ -26,7 +25,7 @@ const fieldOf = (settings, field) => settings[field], refuse = (message) => Effe
 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), {
+})), 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, {

package/dist/storage/json-file.d.ts

@@ -0,0 +1,18 @@
+import { Effect, Option, Schema, Semaphore } from "effect";
+/**
+ * Read the JSON object in `path`: `None` when no file is there. A file that
+ * cannot be read (any error but ENOENT: permissions, a directory) or does
+ * not hold a JSON object fails with `unusable(reason)`.
+ */
+export declare const readJsonObject: <E>(path: string, unusable: (reason: string) => E) => Effect.Effect<Option.Option<Schema.JsonObject>, E>;
+/**
+ * Replace `path` with `value`: written to a temp file of its own beside it
+ * (named by the process and a random number, so concurrent writes never
+ * share one), given `mode` when there is one, then renamed over. A failed
+ * write removes its temp file.
+ */
+export declare const writeJsonObject: <E>(path: string, value: Record<string, unknown>, mode: Option.Option<number>, failed: (reason: string) => E) => Effect.Effect<void, E>;
+/** A lock of its own for `name` at `path` (one refresh of a provider's token kept there, say). */
+export declare const namedLock: (path: string, name: string) => Effect.Effect<Semaphore.Semaphore>;
+/** Run `effect` holding the lock of `path`, which every store in the process that writes the file shares. */
+export declare const withFileLock: (path: string) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;

package/dist/storage/json-file.js

@@ -0,0 +1,26 @@
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { Effect, Option, Random, Schema, Semaphore } from "effect";
+import { errorCodeOf } from "@xandreed/core";
+const decodeJsonObject = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.JsonObject)), isMissing = (cause) => Option.contains(errorCodeOf(cause), "ENOENT");
+export const readJsonObject = (path, unusable) => Effect.tryPromise({ try: () => readFile(path, "utf-8"), catch: (cause) => cause }).pipe(Effect.map(Option.some), Effect.catchIf(isMissing, () => Effect.succeed(Option.none())), Effect.mapError((cause) => unusable(`could not be read (${Option.getOrElse(errorCodeOf(cause), () => String(cause))})`)), Effect.flatMap(Option.match({
+  onNone: () => Effect.succeed(Option.none()),
+  onSome: (text) => decodeJsonObject(text).pipe(Effect.map(Option.some), Effect.mapError(() => unusable("does not hold a JSON object")))
+}))), writeJsonObject = (path, value, mode, failed) => Random.nextIntBetween(0, Number.MAX_SAFE_INTEGER).pipe(Effect.flatMap((suffix) => {
+  const tmp = `${path}.tmp-${process.pid}-${suffix.toString(36)}`;
+  return Effect.tryPromise({
+    try: async () => {
+      await mkdir(dirname(path), { recursive: !0 });
+      await writeFile(tmp, JSON.stringify(value, null, 2), "utf-8");
+      await Option.match(mode, { onNone: () => Promise.resolve(), onSome: (bits) => chmod(tmp, bits) });
+      await rename(tmp, path);
+    },
+    catch: (cause) => failed(String(cause))
+  }).pipe(Effect.tapError(() => Effect.tryPromise({ try: () => rm(tmp, { force: !0 }), catch: (cause) => cause }).pipe(Effect.catch((cause) => Effect.logWarning(`could not remove the temporary file ${tmp}`, cause)))));
+}));
+const locks = new Map, lockOf = (key) => Effect.sync(() => Option.getOrElse(Option.fromNullishOr(locks.get(key)), () => {
+  const made = Semaphore.makeUnsafe(1);
+  locks.set(key, made);
+  return made;
+}));
+export const namedLock = (path, name) => lockOf(`${name}:${resolve(path)}`), withFileLock = (path) => (effect) => Effect.flatMap(namedLock(path, "file"), (lock) => lock.withPermit(effect));

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

@@ -1,5 +1,9 @@
 import { Schema } from "effect";
-/** A proxy URL as an option takes it: a string, or a `Redacted` one when it carries credentials. */
+/**
+ * A proxy URL as an option takes it: a string, or a `Redacted` one when it carries credentials.
+ *
+ * @public
+ */
 export declare const ProxyUrlOption: Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>;
 export type ProxyUrlOption = typeof ProxyUrlOption.Type;
 /**
@@ -11,6 +15,8 @@ export type ProxyUrlOption = typeof ProxyUrlOption.Type;
  * `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.
+ *
+ * @public
  */
 export declare const HttpProxyOptions: Schema.Struct<{
     readonly proxy: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
@@ -74,13 +80,21 @@ declare const ProxyInvalid_base: Schema.Class<ProxyInvalid, Schema.TaggedStruct<
     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. */
+/**
+ * A proxy URL that cannot be used: not a URL, or not `http://` / `https://`. `source` names where it came from.
+ *
+ * @public
+ */
 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. */
+/**
+ * A proxy applies, but this runtime cannot send the call through it: the call is refused rather than sent direct.
+ *
+ * @public
+ */
 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). */

package/dist/transport/model-request.conformance.d.ts

@@ -0,0 +1,13 @@
+import { Effect } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import type { ConformanceCheck } from "@xandreed/core/conformance";
+import type { ResilientHttpError, ResilientHttpResponse } from "./resilient-http-client.adapter.js";
+import type { ProviderFailureProtocol } from "../llm/provider-failure.entity.js";
+/** A fresh logical request over a supplied raw transport; request retries belong to the subject. @public */
+export interface ModelRequestSubject {
+    readonly request: (client: HttpClient.HttpClient, request: HttpClientRequest.HttpClientRequest, options: {
+        readonly protocol: ProviderFailureProtocol;
+    }) => Effect.Effect<Pick<ResilientHttpResponse, "text" | "status">, ResilientHttpError>;
+}
+/** Bounded request-policy contract, independent of provider credentials or a real network. @public */
+export declare const modelRequestConformance: (subject?: ModelRequestSubject) => ReadonlyArray<ConformanceCheck>;

package/dist/transport/model-request.conformance.js

@@ -0,0 +1,36 @@
+import { Effect, Exit, Option, Ref } from "effect";
+import { HttpClient, HttpClientError, HttpClientRequest, HttpClientResponse } from "effect/http";
+import { modelFailureOf } from "@xandreed/core";
+import { check, ConformanceFailure } from "@xandreed/core/conformance";
+import { modelRetryDefaults } from "../llm/model-retry-policy.entity.js";
+import { CurrentModelRetryPolicy } from "../ports/model-retry-policy.port.js";
+import { resilientRequest } from "./resilient-http-client.adapter.js";
+const policy = { ...modelRetryDefaults, totalTimeoutMs: 2000, requestTimeoutMs: 100, bodyIdleTimeoutMs: 100, backoff: { initialMs: 0, maxMs: 0, jitter: 0 } }, request = HttpClientRequest.post("https://conformance.invalid/messages").pipe(HttpClientRequest.bodyJsonUnsafe({ fixture: !0 })), expect = (id, holds, message) => holds ? Effect.void : Effect.fail(new ConformanceFailure({ check: id, message })), response = (request, status, type) => HttpClientResponse.fromWeb(request, Response.json({ error: { type, message: "conformance fixture" } }, { status }));
+export const modelRequestConformance = (subject = { request: resilientRequest }) => [
+  check("uses one counter for transport failures and rejected statuses", "mixed-attempts", () => Effect.gen(function* () {
+    const sends = yield* Ref.make(0), client = HttpClient.make((request) => Effect.flatMap(Ref.getAndUpdate(sends, (n) => n + 1), (ordinal) => ordinal === 0 ? Effect.fail(new HttpClientError.HttpClientError({ reason: new HttpClientError.TransportError({ request, description: "fixture" }) })) : Effect.succeed(ordinal < 3 ? response(request, ordinal === 1 ? 429 : 529, ordinal === 1 ? "rate_limit_error" : "overloaded_error") : HttpClientResponse.fromWeb(request, new Response("ok"))))), result = yield* subject.request(client, request, { protocol: "anthropic" }).pipe(Effect.flatMap((reply) => reply.text), Effect.provideService(CurrentModelRetryPolicy, policy));
+    yield* expect("mixed-attempts", result === "ok" && (yield* Ref.get(sends)) === 4, "mixed failures did not reach one fourth-attempt success");
+  })),
+  check("classifies a structured permanent error before retrying its status", "permanent-status", () => Effect.gen(function* () {
+    const sends = yield* Ref.make(0), client = HttpClient.make((request) => Ref.update(sends, (n) => n + 1).pipe(Effect.as(response(request, 429, "invalid_request_error")))), result = yield* Effect.exit(subject.request(client, request, { protocol: "compat" }).pipe(Effect.provideService(CurrentModelRetryPolicy, policy)));
+    yield* expect("permanent-status", Exit.isFailure(result) && (yield* Ref.get(sends)) === 1 && Option.contains(modelFailureOf(result.cause.reasons.find((reason) => reason._tag === "Fail")?.error), "InvalidRequest"), "a permanent request error was retried or lost its semantic kind");
+  })),
+  check("reads a call's policy at execution and obeys its total attempt limit", "dynamic-policy", () => Effect.gen(function* () {
+    const run = (maxAttempts) => Effect.gen(function* () {
+      const sends = yield* Ref.make(0), client = HttpClient.make((request) => Ref.update(sends, (n) => n + 1).pipe(Effect.as(response(request, 503, "overloaded_error"))));
+      yield* Effect.exit(subject.request(client, request, { protocol: "anthropic" }).pipe(Effect.provideService(CurrentModelRetryPolicy, { ...policy, maxAttempts })));
+      return yield* Ref.get(sends);
+    }), one = yield* run(1), three = yield* run(3);
+    yield* expect("dynamic-policy", one === 1 && three === 3, "a call ignored its policy or repeated beyond its total attempt cap");
+  })),
+  check("never sends a settled request again after its pending headers time out", "settled-headers", () => Effect.gen(function* () {
+    const sends = yield* Ref.make(0), client = HttpClient.make(() => Ref.update(sends, (n) => n + 1).pipe(Effect.andThen(Effect.never))), result = yield* subject.request(client, request, { protocol: "anthropic" }).pipe(Effect.provideService(CurrentModelRetryPolicy, { ...policy, requestTimeoutMs: 50, totalTimeoutMs: 300 }), Effect.exit, Effect.timeoutOption("2 seconds")), timedOut = Option.exists(result, (exit) => Exit.isFailure(exit) && Option.contains(modelFailureOf(exit.cause.reasons.find((reason) => reason._tag === "Fail")?.error), "Timeout"));
+    yield* expect("settled-headers", timedOut && (yield* Ref.get(sends)) === 1, "a settled request was cut before its deadline and sent again, or never timed out");
+  })),
+  check("reads a successful body that loses its connection as a transient failure", "lost-body", () => Effect.gen(function* () {
+    const client = HttpClient.make((request) => Effect.sync(() => HttpClientResponse.fromWeb(request, new Response(new ReadableStream({ start(controller) {
+      controller.error(Error("conformance connection reset"));
+    } }))))), result = yield* subject.request(client, request, { protocol: "anthropic" }).pipe(Effect.flatMap((reply) => reply.text), Effect.exit, Effect.provideService(CurrentModelRetryPolicy, policy));
+    yield* expect("lost-body", Exit.isFailure(result) && Option.contains(modelFailureOf(result.cause.reasons.find((reason) => reason._tag === "Fail")?.error), "Transient"), "a lost connection after handoff became a permanent or unclassified failure");
+  }))
+];

package/dist/transport/models-transport.adapter.d.ts

@@ -1,6 +1,7 @@
-import { Config, Effect, Layer, Option } from "effect";
-import type { Context, Scope } from "effect";
+import { Config, Context, Effect, Layer, Option, Redacted } from "effect";
+import type { Scope } from "effect";
 import { ModelsTransport } from "../ports/models-transport.port.js";
+import type { ModelsFetch, WebSocketProxy } from "../ports/models-transport.port.js";
 import { ProxyUnsupported } from "./http-proxy.entity.js";
 import type { HttpProxyOptions, ProxyInvalid } from "./http-proxy.entity.js";
 /** The runtime the plugin runs on, told apart without a Bun-only import (the subscription's WebSocket checks its route against it too). */
@@ -14,26 +15,26 @@ export type Runtime = {
     readonly _tag: "Other";
 };
 export declare const currentRuntime: () => Runtime;
-/**
- * The transport a proxy setting calls for, or `None` when no proxy applies
- * and nothing has to be held direct: then the plugin adds no transport and
- * every call uses the runtime's own fetch, as it did before the plugin knew
- * proxies (a `FetchHttpClient.Fetch` the host provides still reaches the
- * provider SDKs). With the proxy turned off (`*`) on Node it is a transport
- * over undici's direct agent, since Node's global fetch and agents apply the
- * environment's proxy under `NODE_USE_ENV_PROXY`. A proxy URL that cannot
- * be used fails with `ProxyInvalid`; a runtime that is neither Node nor Bun
- * fails with `ProxyUnsupported` when a proxy applies. Its connection pools
- * close with the scope.
- */
-export declare const modelsTransportFor: (options: HttpProxyOptions) => Effect.Effect<Option.Option<Context.Service.Shape<typeof ModelsTransport>>, ProxyInvalid | ProxyUnsupported | Config.ConfigError, Scope.Scope>;
+export declare const modelsTransportContextFor: (options: {
+    readonly proxy?: string | Redacted.Redacted<string>;
+    readonly noProxy?: string;
+}) => Effect.Effect<Context.Context<never>, ProxyInvalid | ProxyUnsupported | Config.ConfigError, Scope.Scope>;
+/** The scoped transport: a proxy's, or the managed direct one on Node and Bun; none on another runtime without a proxy. */
+export declare const modelsTransportFor: (options: {
+    readonly proxy?: string | Redacted.Redacted<string>;
+    readonly noProxy?: string;
+}) => Effect.Effect<Option.Option<{
+    readonly fetch: ModelsFetch;
+    readonly webSocketAgent?: (target: URL) => Effect.Effect<Option.Option<WebSocketProxy>, ProxyUnsupported>;
+}>, ProxyInvalid | ProxyUnsupported | Config.ConfigError, Scope.Scope>;
 /**
  * `ModelsTransportLive(options)` — the models plugin's network path from a
  * proxy setting: `options.proxy` (or `https_proxy` / `HTTPS_PROXY` and
  * `http_proxy` / `HTTP_PROXY` from the environment) for every call, except
  * loopback hosts and the `noProxy` / `NO_PROXY` hosts, which go direct (see
- * `resolveProxy`). With no proxy at all it is the global fetch, unchanged;
- * with `noProxy: "*"` on Node, undici's direct agent. A proxy URL that cannot
+ * `resolveProxy`). Node always uses a scoped direct undici Agent with its
+ * header/body timeouts disabled; Bun uses its native fetch with fetch's own
+ * timeout turned off. A proxy URL that cannot
  * be used fails with `ProxyInvalid`; a runtime that is neither Node nor Bun
  * fails with `ProxyUnsupported` when a proxy applies. Its connection pools
  * close with the layer's scope. Hosts use it for the OAuth login helpers too:

package/dist/transport/models-transport.adapter.js

@@ -1,18 +1,19 @@
 import { Agent as HttpAgent } from "node:http";
 import { Agent as HttpsAgent } from "node:https";
-import { Config, Effect, Layer, Match, Option, Redacted } from "effect";
-import { ModelsTransport } from "../ports/models-transport.port.js";
+import { Config, Context, Effect, Layer, Match, Option, Redacted } from "effect";
+import { errorCodeOf } from "@xandreed/core";
+import { CurrentManagedModelsTransport, ModelsTransport } from "../ports/models-transport.port.js";
 import { BUN_WEBSOCKET_PROXY_VERSION, NODE_WEBSOCKET_PROXY_VERSION, PROXY_VARIABLES, ProxyUnsupported } from "./http-proxy.entity.js";
-import { atLeastVersion, displayProxy, proxyFor, redactCredentials, resolveProxy, turnsProxyOff, usesProxy } from "./http-proxy.entity.functions.js";
+import { atLeastVersion, displayProxy, proxyFor, redactCredentials, resolveProxy, usesProxy } from "./http-proxy.entity.functions.js";
 import { undiciFetch } from "./undici-fetch.adapter.js";
 export const currentRuntime = () => {
   const versions = typeof process > "u" ? {} : process.versions, bun = versions.bun, node = versions.node;
   return bun !== void 0 ? { _tag: "Bun", version: bun } : node !== void 0 ? { _tag: "Node", version: node } : { _tag: "Other" };
 };
-const readEnvironment = Effect.forEach(PROXY_VARIABLES, (name) => Config.option(Config.String(name)).pipe(Effect.map((value) => Option.toArray(Option.map(value, (text) => [name, text]))))).pipe(Effect.map((entries) => Object.fromEntries(entries.flat()))), targetOf = (input) => typeof input === "string" ? URL.canParse(input) ? Option.some(new URL(input)) : Option.none() : Option.some(input), isSecure = (target) => target.protocol === "https:" || target.protocol === "wss:", describeFailure = (cause) => {
+const readEnvironment = Effect.forEach(PROXY_VARIABLES, (name) => Config.option(Config.String(name)).pipe(Effect.map((value) => Option.toArray(Option.map(value, (text) => [name, text])))), { concurrency: 1 }).pipe(Effect.map((entries) => Object.fromEntries(entries.flat()))), targetOf = (input) => typeof input === "string" ? URL.canParse(input) ? Option.some(new URL(input)) : Option.none() : Option.some(input), isSecure = (target) => target.protocol === "https:" || target.protocol === "wss:", describeFailure = (cause) => {
   const own = cause instanceof Error ? cause.message : String(cause), inner = cause instanceof Error && cause.cause !== void 0 ? cause.cause instanceof Error ? cause.cause.message : String(cause.cause) : "";
   return redactCredentials(inner.length > 0 && inner !== own ? `${own}: ${inner}` : own);
-}, throughProxy = (target, proxy, request) => request.then((response) => response, (cause) => Promise.reject(cause instanceof Error && (cause.name === "AbortError" || cause.name === "TimeoutError") ? cause : TypeError(`the request to ${target.protocol}//${target.host} through the proxy ${displayProxy(proxy)} failed: ${describeFailure(cause)}`, { cause }))), directTransport = ModelsTransport.of({ fetch: (input, init) => globalThis.fetch(input, init) }), webSocketRefused = (target, why) => new ProxyUnsupported({
+}, throughProxy = (target, proxy, request) => request.then((response) => response, (cause) => Promise.reject(cause instanceof Error && (cause.name === "AbortError" || cause.name === "TimeoutError") ? cause : TypeError(`the request to ${target.protocol}//${target.host} through the proxy ${displayProxy(proxy)} failed: ${describeFailure(cause)}`, { cause }))), directTransport = ModelsTransport.of({ fetch: (input, init) => globalThis.fetch(input, init) }), untimed = (init) => ({ ...init, timeout: !1 }), bunDirectTransport = ModelsTransport.of({ fetch: (input, init) => globalThis.fetch(input, untimed(init)) }), webSocketRefused = (target, why) => new ProxyUnsupported({
   message: `${why}, so the WebSocket to ${target.host} is refused instead of connecting directly past the proxy`
 }), refuseProxyAuthentication = (response) => response.status === 407 ? (response.body === null ? Promise.resolve() : response.body.cancel().then(() => {
   return;
@@ -20,29 +21,25 @@ const readEnvironment = Effect.forEach(PROXY_VARIABLES, (name) => Config.option(
   return;
 })).then(() => Promise.reject(Error("the proxy refused its credentials (407 Proxy Authentication Required)"))) : Promise.resolve(response), bunTransport = (config, version) => ModelsTransport.of({
   fetch: (input, init) => Option.match(Option.flatMap(targetOf(input), (target) => Option.map(proxyFor(target, config), (proxy) => [target, proxy])), {
-    onNone: () => globalThis.fetch(input, init),
-    onSome: ([target, proxy]) => throughProxy(target, proxy, globalThis.fetch(input, { ...init, proxy: Redacted.value(proxy) }).then(refuseProxyAuthentication))
+    onNone: () => globalThis.fetch(input, untimed(init)),
+    onSome: ([target, proxy]) => throughProxy(target, proxy, globalThis.fetch(input, { ...untimed(init), proxy: Redacted.value(proxy) }).then(refuseProxyAuthentication))
   }),
   webSocketAgent: (target) => Option.match(proxyFor(target, config), {
     onNone: () => Effect.succeedNone,
     onSome: (url) => atLeastVersion(version, BUN_WEBSOCKET_PROXY_VERSION) ? Effect.succeedSome({ _tag: "Proxy", url }) : Effect.fail(webSocketRefused(target, `Bun ${version} cannot send a WebSocket through a proxy (Bun ${BUN_WEBSOCKET_PROXY_VERSION} and later can)`))
   })
-}), isConnector = (value) => typeof value === "function", codeOf = (error) => ("code" in error) ? error.code : void 0, tunnelOnce = (connect, proxy) => (options, callback) => connect(options, (...result) => {
+}), isConnector = (value) => typeof value === "function", tunnelOnce = (connect, proxy) => (options, callback) => connect(options, (...result) => {
   const [error] = result;
-  return error !== null && codeOf(error) === "UND_ERR_SOCKET" ? callback(Error(`the proxy ${displayProxy(proxy)} closed the connection while opening a tunnel to ${options.hostname}:${options.port.length > 0 ? options.port : options.protocol === "https:" ? "443" : "80"} (${error.message})`, { cause: error }), null) : callback(...result);
+  return error !== null && Option.contains(errorCodeOf(error), "UND_ERR_SOCKET") ? callback(Error(`the proxy ${displayProxy(proxy)} closed the connection while opening a tunnel to ${options.hostname}:${options.port.length > 0 ? options.port : options.protocol === "https:" ? "443" : "80"} (${error.message})`, { cause: error }), null) : callback(...result);
 }), loadUndici = Effect.tryPromise({
   try: () => import("undici"),
-  catch: (cause) => new ProxyUnsupported({ message: `undici, which sends the models plugin's calls on Node under a proxy setting, could not be loaded: ${describeFailure(cause)}` })
-}), nodeDirect = (undici) => Effect.gen(function* () {
-  const dispatcher = new undici.Agent, sockets = { https: new HttpsAgent, http: new HttpAgent };
+  catch: (cause) => new ProxyUnsupported({ message: `undici, which sends the models plugin's calls on Node, could not be loaded: ${describeFailure(cause)}` })
+}), destroyDispatcher = (dispatcher) => Effect.tryPromise({ try: () => dispatcher.destroy(), catch: (cause) => cause }).pipe(Effect.catch((cause) => Effect.logDebug("models transport: a connection pool did not close", cause))), nodeDirect = (undici) => Effect.gen(function* () {
+  const dispatcher = new undici.Agent({ headersTimeout: 0, bodyTimeout: 0 }), sockets = { https: new HttpsAgent, http: new HttpAgent };
   yield* Effect.addFinalizer(() => Effect.all([
-    Effect.promise(() => dispatcher.destroy().then(() => {
-      return;
-    }, () => {
-      return;
-    })),
+    destroyDispatcher(dispatcher),
     Effect.sync(() => [sockets.https, sockets.http].forEach((agent) => agent.destroy()))
-  ], { discard: !0 }));
+  ], { concurrency: 1, discard: !0 }));
   return {
     fetch: undiciFetch(undici.fetch, dispatcher),
     webSocket: (target) => ({ _tag: "Agent", agent: isSecure(target) ? sockets.https : sockets.http })
@@ -53,9 +50,10 @@ const readEnvironment = Effect.forEach(PROXY_VARIABLES, (name) => Config.option(
 }), nodeTransport = (config, version) => Effect.gen(function* () {
   const undici = yield* loadUndici, direct = yield* nodeDirect(undici), proxyAgent = (proxy) => new undici.ProxyAgent({
     uri: Redacted.value(proxy),
+    clientFactory: (origin, options) => new undici.Pool(origin, { ...options, headersTimeout: 0, bodyTimeout: 0 }),
     factory: (origin, options) => {
       const connect = Reflect.get(options, "connect");
-      return new undici.Pool(origin, { ...options, ...isConnector(connect) ? { connect: tunnelOnce(connect, proxy) } : {} });
+      return new undici.Pool(origin, { ...options, ...isConnector(connect) ? { connect: tunnelOnce(connect, proxy) } : {}, headersTimeout: 0, bodyTimeout: 0 });
     }
   }), sameUrl = Option.isSome(config.https) && Option.isSome(config.http) && Redacted.value(config.https.value) === Redacted.value(config.http.value), route = (proxy) => {
     const dispatcher = proxyAgent(proxy);
@@ -65,13 +63,9 @@ const readEnvironment = Effect.forEach(PROXY_VARIABLES, (name) => Config.option(
     http: Option.map(config.http, (proxy) => new HttpAgent({ proxyEnv: { HTTP_PROXY: Redacted.value(proxy) } }))
   }, dispatchers = [...Option.toArray(Option.map(httpsRoute, (route) => route.dispatcher)), ...sameUrl ? [] : Option.toArray(Option.map(httpRoute, (route) => route.dispatcher))];
   yield* Effect.addFinalizer(() => Effect.all([
-    Effect.forEach(dispatchers, (dispatcher) => Effect.promise(() => dispatcher.destroy().then(() => {
-      return;
-    }, () => {
-      return;
-    })), { discard: !0 }),
+    Effect.forEach(dispatchers, destroyDispatcher, { concurrency: 1, discard: !0 }),
     Effect.sync(() => [...Option.toArray(socketAgents.https), ...Option.toArray(socketAgents.http)].forEach((agent) => agent.destroy()))
-  ], { discard: !0 }));
+  ], { concurrency: 1, discard: !0 }));
   const routeFor = (target) => Option.flatMap(proxyFor(target, config), () => isSecure(target) ? httpsRoute : httpRoute), fetch = (input, init) => Option.match(Option.flatMap(targetOf(input), (target) => Option.map(routeFor(target), (route) => [target, route])), {
     onNone: () => direct.fetch(input, init),
     onSome: ([target, route]) => throughProxy(target, route.proxy, route.fetch(input, init))
@@ -83,15 +77,18 @@ const readEnvironment = Effect.forEach(PROXY_VARIABLES, (name) => Config.option(
       onSome: (agent) => atLeastVersion(version, NODE_WEBSOCKET_PROXY_VERSION) ? Effect.succeedSome({ _tag: "Agent", agent }) : Effect.fail(webSocketRefused(target, `Node ${version} ignores the proxyEnv option of https.Agent (Node ${NODE_WEBSOCKET_PROXY_VERSION} and later honour it)`))
     })
   });
-});
-export const modelsTransportFor = (options) => Effect.gen(function* () {
+}), managedDirect = (transport) => Context.make(ModelsTransport, transport).pipe(Context.add(CurrentManagedModelsTransport, Option.some(transport)));
+export const modelsTransportContextFor = Effect.fnUntraced(function* (options) {
   const config = yield* Effect.fromResult(resolveProxy(options, yield* readEnvironment)), runtime = currentRuntime();
   if (!usesProxy(config))
-    return yield* Match.value(runtime).pipe(Match.tag("Node", () => turnsProxyOff(config) ? Effect.map(nodeDirectTransport, Option.some) : Effect.succeedNone), Match.orElse(() => Effect.succeedNone));
-  return Option.some(yield* Match.value(runtime).pipe(Match.tag("Bun", ({ version }) => Effect.succeed(bunTransport(config, version))), Match.tag("Node", ({ version }) => nodeTransport(config, version)), Match.tag("Other", () => Effect.fail(new ProxyUnsupported({
+    return yield* Match.value(runtime).pipe(Match.tag("Node", () => Effect.map(nodeDirectTransport, managedDirect)), Match.tag("Bun", () => Effect.succeed(managedDirect(bunDirectTransport))), Match.orElse(() => Effect.succeed(Context.empty())));
+  const transport = yield* Match.value(runtime).pipe(Match.tag("Bun", ({ version }) => Effect.succeed(bunTransport(config, version))), Match.tag("Node", ({ version }) => nodeTransport(config, version)), Match.tag("Other", () => Effect.fail(new ProxyUnsupported({
     message: "a proxy is configured, but this runtime is neither Node nor Bun: the models plugin cannot send its calls through a proxy here"
-  }))), Match.exhaustive));
-}), ModelsTransportLive = (options = {}) => Layer.effect(ModelsTransport, Effect.map(modelsTransportFor(options), Option.getOrElse(() => directTransport))), transportFetch = (transport) => Object.assign((input, init) => input instanceof Request ? input.arrayBuffer().then((body) => transport.fetch(input.url, {
+  }))), Match.exhaustive);
+  return Context.make(ModelsTransport, transport).pipe(Context.add(CurrentManagedModelsTransport, Option.none()));
+}), modelsTransportFor = Effect.fnUntraced(function* (options) {
+  return Context.getOption(yield* modelsTransportContextFor(options), ModelsTransport);
+}), ModelsTransportLive = (options = {}) => Layer.effectContext(Effect.map(modelsTransportContextFor(options), (context) => Context.add(context, ModelsTransport, Option.getOrElse(Context.getOption(context, ModelsTransport), () => directTransport)))), transportFetch = (transport) => Object.assign((input, init) => input instanceof Request ? input.arrayBuffer().then((body) => transport.fetch(input.url, {
   method: input.method,
   headers: input.headers,
   body: body.byteLength === 0 ? null : body,