Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* Decision-model configuration: flat `decision_model_*` keys in the
* operator's machine config (never the vault), each with an
* `OPEN_SECOND_BRAIN_DECISION_MODEL_*` environment override.
*
* The feature is ACTIVE only when both of these hold at once:
* 1. the operator explicitly set `decision_model_enabled: "true"`, and
* 2. the environment variable named by `decision_model_env_key` (or the
* preset's default name) is set to a non-empty value. The one
* exception is a self-hosted server on a loopback host whose preset
* makes the key optional (`laya`, `openjev`): nothing
* leaves the machine, so no key is needed.
* Everything else is off.
*
* Per-use modes are held to the provider's threshold profile
* (`questions.ts`): an `enforce` setting on a use without tuned
* thresholds for that profile runs as `shadow`, and only the diagnostics
* say so. A missing key is a normal state rather than an
* error: it is reported only by the explicit diagnostics
* (`o2b decision-model check`, the doctor readiness line), and every other
* surface behaves exactly as it does without the feature.
*
* The key itself is never stored. The resolved config carries only the
* variable's NAME and whether it is set; the adapter reads the value at
* call time.
*
* Resolution never throws. Invalid values are collected into `errors`
* (each naming its key) and the status becomes `invalid`, which every hot
* path treats as off and the diagnostics report with a non-zero exit.
*/
import { assertHttpEgressEndpoint } from "../search/embeddings/http-util.ts";
import {
SecretStoreKeyfileMissingError,
SecretStoreLockedError,
} from "../brain/secrets/envelope.ts";
import { SecretReferenceError } from "../secret-ref.ts";
import { isSecretReferenceValue, resolveNamedSecret } from "../secret-resolver.ts";
import { envOrConfig } from "../validate.ts";
import {
DECISION_MODEL_USES,
isDecisionModelMode,
isDecisionModelUse,
type DecisionModelMode,
type DecisionModelUse,
} from "./contract.ts";
import {
DECISION_MODEL_CHAT_SHAPED_ADAPTERS,
DECISION_MODEL_HOSTED_MAX_STATE_TOKENS,
DECISION_MODEL_PRESET_NAMES,
DECISION_MODEL_PRESETS,
DECISION_MODEL_WIRE_MAX_CHOICE_OPTIONS,
decisionModelPreset,
} from "./presets.ts";
import { isLoopbackUrl, parseDecisionModelPrivateUses, withoutUserinfo } from "./egress-guard.ts";
import { machineTunedMarkReader } from "./eval/mark.ts";
import {
DECISION_THRESHOLD_PROFILE_NAMES,
isDecisionThresholdProfile,
thresholdsTunedFor,
} from "./questions.ts";
import {
decisionThresholdsPath,
EMPTY_THRESHOLD_STORE,
readThresholdsStore,
storedThresholdEntry,
type DecisionThresholdsStore,
} from "./thresholds.ts";
export const DECISION_MODEL_DEFAULTS = Object.freeze({
timeoutMs: 3000,
hookBudgetMs: 700,
dailyCostGateUsd: 0.5,
});
export type {
DecisionModelStatus,
DecisionModelUses,
ResolvedDecisionModelConfig,
} from "./config-types.ts";
export type { ResolvedDecisionProvider } from "./config-types.ts";
export { resolvedProviderEntries } from "./provider-entries.ts";
import type {
DecisionModelStatus,
DecisionModelUses,
ResolvedDecisionModelConfig,
ResolvedDecisionProvider,
} from "./config-types.ts";
const ENV_PREFIX = "OPEN_SECOND_BRAIN_DECISION_MODEL_";
/**
* What `decision_model_env_key` must look like: an environment variable
* NAME (the same rule the secrets store applies). Anything else, such as a
* key pasted where its variable's name belongs, is an invalid config, and
* the value is never repeated in a message.
*/
const ENV_VAR_NAME_RE = /^[A-Z_][A-Z0-9_]*$/;
/**
* The modes the uses actually run in: `enforce` becomes `shadow` for every
* use the `tunedFor` gate refuses. The gate (see {@link entryTunedGate})
* is the source table, the local thresholds store and the injected
* measured reader (the machine-side tuning mark, `eval/mark.ts`) OR-ed
* per use.
*/
function holdToProfile(
uses: DecisionModelUses,
tunedFor: (use: DecisionModelUse) => boolean,
): { readonly uses: DecisionModelUses; readonly shadowOnly: ReadonlyArray<DecisionModelUse> } {
const shadowOnly = DECISION_MODEL_USES.filter((use) => uses[use] === "enforce" && !tunedFor(use));
if (shadowOnly.length === 0) return { uses, shadowOnly: Object.freeze([]) };
const out: Record<DecisionModelUse, DecisionModelMode> = { ...uses };
for (const use of shadowOnly) out[use] = "shadow";
return { uses: Object.freeze(out), shadowOnly: Object.freeze(shadowOnly) };
}
function setting(
env: NodeJS.ProcessEnv,
config: Readonly<Record<string, string>>,
suffix: string,
): string | null {
const key = `decision_model_${suffix}`;
return envOrConfig(env, config, `${ENV_PREFIX}${suffix.toUpperCase()}`, key);
}
/**
* The key value for presence, with reference routing. A value written as
* a `$secret:NAME` reference resolves through the custody store of
* `secretsVault` (store first, env fallback); an unresolvable reference, a
* store-held name under a locked envelope, or a store whose keyfile is
* missing while entries survive lands in `errors` as the named refusal -
* with the status turning `invalid` - never as a silent empty key.
* Without a vault the value is taken as-is, exactly as before the routing
* existed, and resolution still never throws.
*/
function resolveKeyValue(
raw: string | undefined,
secretsVault: string | null | undefined,
errors: string[],
): string | undefined {
if (typeof raw !== "string" || secretsVault === null || secretsVault === undefined) return raw;
if (!isSecretReferenceValue(raw)) return raw;
try {
return resolveNamedSecret(secretsVault, raw.trim());
} catch (err) {
if (
err instanceof SecretReferenceError ||
err instanceof SecretStoreLockedError ||
err instanceof SecretStoreKeyfileMissingError
) {
errors.push(err.message);
return undefined;
}
throw err;
}
}
const ALL_OFF: DecisionModelUses = Object.freeze(
Object.fromEntries(DECISION_MODEL_USES.map((use) => [use, "off"])) as Record<
DecisionModelUse,
DecisionModelMode
>,
);
/**
* Parse `decision_model_uses` (`use:mode` comma list). Unknown uses or
* modes are errors naming the key.
*/
export function parseDecisionModelUses(raw: string | null, errors: string[]): DecisionModelUses {
if (raw === null || raw.trim() === "") return ALL_OFF;
const out: Record<DecisionModelUse, DecisionModelMode> = { ...ALL_OFF };
const seen = new Set<string>();
for (const part of raw.split(",")) {
const entry = part.trim();
if (entry === "") continue;
const sep = entry.indexOf(":");
const use = (sep < 0 ? entry : entry.slice(0, sep)).trim();
const mode = sep < 0 ? "" : entry.slice(sep + 1).trim();
if (!isDecisionModelUse(use)) {
errors.push(
`decision_model_uses: unknown use '${use}' (expected one of ${DECISION_MODEL_USES.join(", ")})`,
);
continue;
}
if (!isDecisionModelMode(mode)) {
errors.push(
`decision_model_uses: use '${use}' needs a mode off, shadow or enforce, got '${mode}'`,
);
continue;
}
if (seen.has(use)) {
errors.push(`decision_model_uses: use '${use}' is listed more than once`);
continue;
}
seen.add(use);
out[use] = mode;
}
return Object.freeze(out);
}
function parseBoolSetting(raw: string | null, key: string, errors: string[]): boolean {
if (raw === null) return false;
if (raw === "true" || raw === "1") return true;
if (raw === "false" || raw === "0") return false;
errors.push(`${key} must be 'true' or 'false', got '${raw}'`);
return false;
}
function parseIntSetting(
raw: string | null,
fallback: number,
key: string,
errors: string[],
): number {
if (raw === null) return fallback;
const n = Number(raw);
if (!Number.isInteger(n) || n < 1) {
errors.push(`${key} must be a positive integer, got '${raw}'`);
return fallback;
}
return n;
}
function parseNonNegativeSetting(
raw: string | null,
fallback: number | null,
key: string,
errors: string[],
): number | null {
if (raw === null) return fallback;
const n = Number(raw);
if (!Number.isFinite(n) || n < 0) {
errors.push(`${key} must be a number >= 0, got '${raw}'`);
return fallback;
}
return n;
}
export interface ResolveDecisionModelOptions {
readonly env?: NodeJS.ProcessEnv;
/** The operator's flat machine config (already discovered and parsed). */
readonly config: Readonly<Record<string, string>>;
/** Vault whose `_brain.yaml` may opt out; null when there is none. */
readonly vault: string | null;
/**
* Vault whose custody store backs `$secret:` references in the key
* value; absent, a reference-shaped key value is taken as-is, exactly
* as before the resolver routing existed.
*/
readonly secretsVault?: string | null;
/**
* Reads the vault opt-out. Injected so this module never imports the
* whole policy loader at startup; defaults to the real loader.
*/
readonly vaultOptOut?: (vault: string) => boolean;
/**
* The measured-tune reader: consulted only when the source table says
* a use is untuned for the resolved profile. Undefined (the default)
* reads the machine-side tuning marks under the platform state root -
* one TTL-cached file read per untuned pair per minute; null disables
* the measured path entirely, which is the behavior every hand-edit
* test pins.
*/
readonly measuredTunedMark?: ((profile: string | null, use: DecisionModelUse) => boolean) | null;
/**
* Where the local thresholds store (`decision-thresholds.json`,
* `thresholds.ts`) lives. Undefined reads the file beside the default
* config path - the production behavior; a path reads that file (the
* CLI passes the `--config` sibling); null disables the store, which
* is the behavior the hand-edit tests pin.
*/
readonly thresholdsPath?: string | null;
}
/**
* The thresholds store this resolution gates against, read lazily (only
* an enforce hold that the table refuses consults it) and TTL-cached
* inside the store module. `null` (the option set to null) disables the
* store: the empty store tunes nothing.
*/
function thresholdsStoreFor(opts: ResolveDecisionModelOptions): DecisionThresholdsStore {
const path = thresholdsPathFor(opts);
return path === null ? EMPTY_THRESHOLD_STORE : readThresholdsStore(path);
}
/** The thresholds store path this resolution reads; null when disabled. */
function thresholdsPathFor(opts: ResolveDecisionModelOptions): string | null {
if (opts.thresholdsPath === null) return null;
if (opts.thresholdsPath !== undefined) return opts.thresholdsPath;
// The file beside the config path this process resolves: an explicit
// OPEN_SECOND_BRAIN_CONFIG in the resolution's environment names it, as
// it does for every other config read; otherwise the process's default
// discovery (env, XDG, home) applies. Lazy, as in the policy require
// above: core/config is a large module and only this store read needs
// its discovery chain.
const env = opts.env ?? process.env;
const explicit = env["OPEN_SECOND_BRAIN_CONFIG"];
const coreConfig = require("../config.ts") as typeof import("../config.ts");
const configPath =
typeof explicit === "string" && explicit !== "" ? explicit : coreConfig.defaultConfigPath();
return decisionThresholdsPath(configPath);
}
/**
* The tuned gate for one chain entry: the source table (baseline or a
* hand-registered list) OR the local store entry for THIS entry's model
* id, keyed by the model the server reports - never the preset - OR the
* measured mark. The store is consulted only when the table refuses, so
* a baseline model pays no store read.
*/
function entryTunedGate(
store: DecisionThresholdsStore,
profile: string | null,
model: string | null,
vault: string | null,
measuredTuned: ((use: DecisionModelUse) => boolean) | null,
): (use: DecisionModelUse) => boolean {
return (use) =>
thresholdsTunedFor(profile, use, measuredTuned === null ? null : () => measuredTuned(use)) ||
storedThresholdEntry(store, model, use, vault) !== null;
}
function defaultVaultOptOut(vault: string): boolean {
// Lazy: only reached when the feature is enabled AND a key is set.
// eslint-disable-next-line @typescript-eslint/no-require-imports
const policy = require("../brain/policy.ts") as typeof import("../brain/policy.ts");
try {
return policy.decisionModelDisabledByVault(policy.loadBrainConfig(vault));
} catch {
// Absent config: no opt-out. Present but unreadable: the vault's wish
// cannot be known, so the feature stays off for it (fail closed for
// egress).
return policy.brainConfigReadFailure(vault) !== null;
}
}
/**
* Resolve the decision-model configuration. Never throws; see the module
* header for the status rules.
*/
export function resolveDecisionModelConfig(
opts: ResolveDecisionModelOptions,
): ResolvedDecisionModelConfig {
const env = opts.env ?? process.env;
const config = opts.config;
const notes: string[] = [];
const errors: string[] = [];
const enabledRaw = setting(env, config, "enabled");
const enabled = enabledRaw === "true" || enabledRaw === "1";
if (enabledRaw !== null && !enabled && enabledRaw !== "false" && enabledRaw !== "0") {
notes.push(`decision_model_enabled '${enabledRaw}' is not 'true', so the feature is off`);
}
// The ordered provider chain (`decision_model_providers`, issue #264).
// `decision_model_provider` stays the one-element form; when both are
// set the list wins and a note says so. Parsing collects errors naming
// the key; the list is only non-empty when every entry parsed.
const providersRaw = setting(env, config, "providers");
const providerRaw = setting(env, config, "provider");
const chainNames: string[] = [];
if (providersRaw !== null) {
const seen = new Set<string>();
for (const part of providersRaw.split(",")) {
const name = part.trim();
if (name === "") continue;
if (!Object.hasOwn(DECISION_MODEL_PRESETS, name)) {
errors.push(
`decision_model_providers must be one of ${DECISION_MODEL_PRESET_NAMES.join(", ")}, ` +
`got '${name}'`,
);
} else if (seen.has(name)) {
errors.push(`decision_model_providers: provider '${name}' is listed more than once`);
} else {
seen.add(name);
chainNames.push(name);
}
}
if (chainNames.length === 0) {
errors.push(
`decision_model_providers must name at least one provider preset ` +
`(one of ${DECISION_MODEL_PRESET_NAMES.join(", ")})`,
);
}
if (providerRaw !== null && providerRaw !== (chainNames[0] ?? null)) {
notes.push(
`decision_model_provider '${providerRaw}' is ignored while decision_model_providers ` +
"is set; the list decides the order",
);
}
}
const primaryName = chainNames[0] ?? providerRaw;
// Per-entry endpoint overrides (`decision_model_providers_<preset>
// _base_url|_id|_env_key`): any entry can name its own endpoint, so a
// preset without one (compatible) can sit anywhere in the chain and a
// preset with a default (typesafe, laya) can be pointed elsewhere.
// Config only: the chain is a deployment fact, so these keys have no
// environment override.
const entryOverride = (name: string, suffix: string): string | null => {
const value = config[`decision_model_providers_${name}_${suffix}`];
return typeof value === "string" && value.trim() !== "" ? value : null;
};
const primaryBaseOverride = primaryName !== null ? entryOverride(primaryName, "base_url") : null;
const primaryIdOverride = primaryName !== null ? entryOverride(primaryName, "id") : null;
const primaryEnvOverride = primaryName !== null ? entryOverride(primaryName, "env_key") : null;
const preset = primaryName !== null ? decisionModelPreset(primaryName) : null;
const explicitBaseUrl = primaryBaseOverride ?? setting(env, config, "base_url");
const baseUrlRaw = explicitBaseUrl ?? preset?.baseUrl ?? null;
const cleanedUrl = baseUrlRaw !== null ? withoutUserinfo(baseUrlRaw.replace(/\/+$/, "")) : null;
const baseUrl = cleanedUrl?.url ?? null;
const model = primaryIdOverride ?? setting(env, config, "id") ?? preset?.model ?? null;
const envKeyRaw = primaryEnvOverride ?? setting(env, config, "env_key") ?? preset?.envKey ?? null;
const envKeyValid = envKeyRaw === null || ENV_VAR_NAME_RE.test(envKeyRaw);
// An invalid name is never looked up and never reported back.
const envKey = envKeyValid ? envKeyRaw : null;
const keyValue = resolveKeyValue(
envKey !== null ? env[envKey] : undefined,
opts.secretsVault,
errors,
);
const keyPresent = typeof keyValue === "string" && keyValue.trim() !== "";
const configuredUses = parseDecisionModelUses(setting(env, config, "uses"), []);
if (!enabled) {
return Object.freeze({
status: "disabled",
errors: Object.freeze([]),
notes: Object.freeze(notes),
enabled: false,
provider: primaryName,
adapter: preset?.adapter ?? "systemone",
baseUrl,
model,
envKey,
keyPresent,
keyRequired: true,
allowInsecureHttp: false,
timeoutMs: DECISION_MODEL_DEFAULTS.timeoutMs,
hookBudgetMs: DECISION_MODEL_DEFAULTS.hookBudgetMs,
maxStateTokens:
preset?.defaultStateTokens ??
preset?.maxStateTokens ??
DECISION_MODEL_HOSTED_MAX_STATE_TOKENS,
maxChoiceOptions: preset?.maxChoiceOptions ?? DECISION_MODEL_WIRE_MAX_CHOICE_OPTIONS,
uses: ALL_OFF,
configuredUses,
dailyCostGateUsd: DECISION_MODEL_DEFAULTS.dailyCostGateUsd,
inputPriceUsdPerMtok: preset?.inputPriceUsdPerMtok ?? null,
outputPriceUsdPerMtok: null,
allowUncalibrated: false,
calibrated: preset?.calibrated ?? true,
thresholdProfile: preset?.thresholdProfile ?? null,
shadowOnlyUses: Object.freeze([]),
licenceNote: preset?.licenceNote ?? null,
processor: preset?.processor ?? null,
vault: opts.vault,
});
}
if (providersRaw === null) {
if (providerRaw === null) {
errors.push(
`decision_model_provider is required when decision_model_enabled is true ` +
`(one of ${DECISION_MODEL_PRESET_NAMES.join(", ")})`,
);
} else if (preset === null) {
errors.push(
`decision_model_provider must be one of ${DECISION_MODEL_PRESET_NAMES.join(", ")}, ` +
`got '${providerRaw}'`,
);
}
}
// The first entry's endpoint keys: the single form's messages stay
// byte-identical; the list form names the per-entry key beside the
// global one, since both configure this entry.
if (preset !== null && baseUrl === null) {
if (providersRaw === null) {
errors.push(`decision_model_base_url is required for provider '${preset.name}'`);
} else {
errors.push(
`decision_model_providers: provider '${preset.name}' needs an endpoint: set ` +
`decision_model_providers_${preset.name}_base_url (or decision_model_base_url, ` +
"which the first provider reads)",
);
}
}
if (preset !== null && model === null) {
if (providersRaw === null) {
errors.push(`decision_model_id is required for provider '${preset.name}'`);
} else {
errors.push(
`decision_model_providers: provider '${preset.name}' needs a pinned model: set ` +
`decision_model_providers_${preset.name}_id (or decision_model_id, which the ` +
"first provider reads)",
);
}
}
if (model !== null && /(^|[-/])latest$/i.test(model)) {
errors.push(`decision_model_id must pin a model version, not a moving alias ('${model}')`);
}
if (!envKeyValid) {
const perEntryKey =
primaryName !== null &&
primaryEnvOverride !== null &&
!ENV_VAR_NAME_RE.test(primaryEnvOverride)
? `decision_model_providers_${primaryName}_env_key`
: null;
errors.push(
(perEntryKey ?? "decision_model_env_key") +
" must be the NAME of an environment variable " +
"(A-Z, 0-9 and _), not the key itself; the value is not shown",
);
}
if (cleanedUrl?.hadUserinfo === true) {
errors.push(
"decision_model_base_url must not carry user:password@ credentials; " +
"the key is sent in a header from decision_model_env_key",
);
}
const allowInsecureHttp = parseBoolSetting(
setting(env, config, "allow_insecure_http"),
"decision_model_allow_insecure_http",
errors,
);
if (baseUrl !== null && cleanedUrl?.hadUserinfo !== true) {
try {
assertHttpEgressEndpoint(baseUrl, "decision_model_base_url", {
allowInsecureHttp,
key: "decision_model_allow_insecure_http",
});
} catch (err) {
errors.push((err as Error).message);
}
}
const timeoutMs = parseIntSetting(
setting(env, config, "timeout_ms"),
DECISION_MODEL_DEFAULTS.timeoutMs,
"decision_model_timeout_ms",
errors,
);
const hookBudgetMs = parseIntSetting(
setting(env, config, "hook_budget_ms"),
DECISION_MODEL_DEFAULTS.hookBudgetMs,
"decision_model_hook_budget_ms",
errors,
);
const presetMax = preset?.maxStateTokens ?? DECISION_MODEL_HOSTED_MAX_STATE_TOKENS;
const maxStateRequested = parseIntSetting(
setting(env, config, "max_state_tokens"),
preset?.defaultStateTokens ?? presetMax,
"decision_model_max_state_tokens",
errors,
);
if (maxStateRequested > presetMax) {
notes.push(
`decision_model_max_state_tokens ${maxStateRequested} is above the preset maximum ` +
`${presetMax}; clamped`,
);
}
const maxStateTokens = Math.min(maxStateRequested, presetMax);
const configured = parseDecisionModelUses(setting(env, config, "uses"), errors);
const privateHostedUses = parseDecisionModelPrivateUses(
setting(env, config, "private_uses"),
errors,
);
const dailyCostGateUsd =
parseNonNegativeSetting(
setting(env, config, "cost_gate_usd"),
DECISION_MODEL_DEFAULTS.dailyCostGateUsd,
"decision_model_cost_gate_usd",
errors,
) ?? DECISION_MODEL_DEFAULTS.dailyCostGateUsd;
const inputPriceConfigured = parseNonNegativeSetting(
setting(env, config, "input_price_usd_per_mtok"),
preset?.inputPriceUsdPerMtok ?? null,
"decision_model_input_price_usd_per_mtok",
errors,
);
const outputPriceRaw = parseNonNegativeSetting(
setting(env, config, "output_price_usd_per_mtok"),
null,
"decision_model_output_price_usd_per_mtok",
errors,
);
// A chat-shaped route (DECISION_MODEL_CHAT_SHAPED_ADAPTERS, derived from
// the preset table) asks a generative model to write the answer as text,
// so the request bills output tokens like input ones; any other route's
// published price covers the reply.
const chatShaped =
preset !== null && DECISION_MODEL_CHAT_SHAPED_ADAPTERS.includes(preset.adapter);
if (!chatShaped && outputPriceRaw !== null) {
notes.push(
"decision_model_output_price_usd_per_mtok is read only for chat-shaped routes, where a " +
"generative model bills output; other routes do not bill output, so it is ignored",
);
}
// A chat model bills output too: with either price unknown, so is the cost.
const inputPriceUsdPerMtok =
chatShaped && (inputPriceConfigured === null || outputPriceRaw === null)
? null
: inputPriceConfigured;
const outputPriceUsdPerMtok = chatShaped ? outputPriceRaw : null;
if (chatShaped && inputPriceUsdPerMtok === null) {
notes.push(
"this chat-shaped route's cost is unknown (cost_source: unknown) unless the route reports " +
"it or both decision_model_input_price_usd_per_mtok and " +
"decision_model_output_price_usd_per_mtok are set",
);
}
const allowUncalibrated = parseBoolSetting(
setting(env, config, "allow_uncalibrated"),
"decision_model_allow_uncalibrated",
errors,
);
const calibrated = preset?.calibrated ?? true;
if (!calibrated && !allowUncalibrated) {
const enforced = DECISION_MODEL_USES.filter((use) => configured[use] === "enforce");
if (enforced.length > 0) {
errors.push(
`decision_model_uses: enforce (${enforced.join(", ")}) needs a calibrated provider; ` +
`set decision_model_allow_uncalibrated: true to allow provider '${primaryName}'`,
);
}
}
// The threshold profile. Only a `compatible` server may name one, since
// only the operator knows which model family it serves; every other
// preset carries its own, and an uncalibrated route never borrows a
// calibrated family's thresholds.
const profileRaw = setting(env, config, "threshold_profile");
let thresholdProfile = preset?.thresholdProfile ?? null;
if (profileRaw !== null && profileRaw !== "") {
if (!isDecisionThresholdProfile(profileRaw)) {
errors.push(
`decision_model_threshold_profile must be one of ` +
`${DECISION_THRESHOLD_PROFILE_NAMES.join(", ")}, got '${profileRaw}'`,
);
} else if (preset?.name === "compatible") {
thresholdProfile = profileRaw;
} else if (profileRaw !== thresholdProfile) {
notes.push(
`decision_model_threshold_profile is read only for provider 'compatible'; ` +
`provider '${primaryName}' keeps its own profile (${thresholdProfile ?? "none"})`,
);
}
}
// The measured-mark reader bound to one entry's endpoint. Disabled
// reader (null): the table alone decides. Default (undefined): the
// machine-side marks, TTL-cached inside the mark module, bound to THIS
// entry's endpoint - a mark earned by another provider, model or base
// URL never arms enforce here.
const markReaderFor = (
endpoint: {
readonly provider: string | null;
readonly model: string | null;
readonly baseUrl: string | null;
},
profile: string | null,
): ((use: DecisionModelUse) => boolean) | null => {
if (profile === null) return null;
return (use) => {
if (opts.measuredTunedMark === null) return false;
const reader = opts.measuredTunedMark ?? machineTunedMarkReader(endpoint);
return reader(profile, use);
};
};
// The store is read only when a use is configured enforce: shadow and
// off installs pay no file read at all.
const needsGate = DECISION_MODEL_USES.some((use) => configured[use] === "enforce");
let storeCache: DecisionThresholdsStore | null = null;
const store = (): DecisionThresholdsStore => {
if (storeCache === null) storeCache = thresholdsStoreFor(opts);
return storeCache;
};
const held = holdToProfile(
configured,
needsGate
? entryTunedGate(
store(),
thresholdProfile,
model,
opts.vault,
markReaderFor({ provider: primaryName, model, baseUrl }, thresholdProfile),
)
: () => true,
);
const uses = held.uses;
// A self-hosted server on this machine needs no key; anything that leaves
// the machine does.
const keyRequired = !(preset?.keyOptionalOnLoopback === true && isLoopbackUrl(baseUrl));
// The first chain entry, as resolved above from the preset plus the
// endpoint override keys. Its fields mirror the config's top level, so
// every reader written for the single-provider era keeps working.
const firstEntry: ResolvedDecisionProvider = {
name: primaryName ?? "unknown",
adapter: preset?.adapter ?? "systemone",
baseUrl,
model,
envKey,
keyPresent,
keyRequired,
maxStateTokens,
maxChoiceOptions: preset?.maxChoiceOptions ?? DECISION_MODEL_WIRE_MAX_CHOICE_OPTIONS,
calibrated,
inputPriceUsdPerMtok,
outputPriceUsdPerMtok: outputPriceUsdPerMtok ?? null,
thresholdProfile,
licenceNote: preset?.licenceNote ?? null,
processor: preset?.processor ?? null,
uses,
shadowOnlyUses: held.shadowOnly,
};
// Entries after the first resolve like the first one, minus the global
// endpoint keys: preset defaults, overridden per entry by
// `decision_model_providers_<preset>_*`. An entry that cannot resolve
// an endpoint is a config error naming its key - a silently skipped
// fallback would hide the typo.
const laterEntries: ResolvedDecisionProvider[] = [];
for (const [index, name] of chainNames.entries()) {
if (index === 0) continue;
const laterPreset = DECISION_MODEL_PRESETS[name];
if (laterPreset === undefined) continue;
const laterUrlRaw = entryOverride(name, "base_url") ?? laterPreset.baseUrl;
const laterModel = entryOverride(name, "id") ?? laterPreset.model;
const laterEnvKeyRaw = entryOverride(name, "env_key") ?? laterPreset.envKey;
if (laterUrlRaw === null) {
errors.push(
`decision_model_providers: provider '${name}' needs an endpoint: set ` +
`decision_model_providers_${name}_base_url (its preset carries none)`,
);
continue;
}
if (laterModel === null) {
errors.push(
`decision_model_providers: provider '${name}' needs a pinned model: set ` +
`decision_model_providers_${name}_id`,
);
continue;
}
if (/(^|[-/])latest$/i.test(laterModel)) {
errors.push(
`decision_model_providers_${name}_id must pin a model version, ` +
`not a moving alias ('${laterModel}')`,
);
continue;
}
const laterEnvKeyValid = laterEnvKeyRaw === null || ENV_VAR_NAME_RE.test(laterEnvKeyRaw);
if (!laterEnvKeyValid) {
errors.push(
`decision_model_providers_${name}_env_key must be the NAME of an environment ` +
"variable (A-Z, 0-9 and _), not the key itself; the value is not shown",
);
continue;
}
const laterCleaned = withoutUserinfo(laterUrlRaw.replace(/\/+$/, ""));
if (laterCleaned.hadUserinfo) {
errors.push(
`decision_model_providers_${name}_base_url must not carry user:password@ ` +
"credentials; the key is sent in a header from its env_key",
);
continue;
}
try {
assertHttpEgressEndpoint(laterCleaned.url, `decision_model_providers_${name}_base_url`, {
allowInsecureHttp,
key: "decision_model_allow_insecure_http",
});
} catch (err) {
errors.push((err as Error).message);
continue;
}
const laterKeyValue = resolveKeyValue(
laterEnvKeyRaw !== null ? env[laterEnvKeyRaw] : undefined,
opts.secretsVault,
errors,
);
const laterKeyPresent = typeof laterKeyValue === "string" && laterKeyValue.trim() !== "";
const laterKeyRequired = !(
laterPreset.keyOptionalOnLoopback === true && isLoopbackUrl(laterCleaned.url)
);
const laterHeld = holdToProfile(
configured,
entryTunedGate(
store(),
laterPreset.thresholdProfile,
laterModel,
opts.vault,
markReaderFor(
{ provider: laterPreset.name, model: laterModel, baseUrl: laterCleaned.url },
laterPreset.thresholdProfile,
),
),
);
laterEntries.push({
name: laterPreset.name,
adapter: laterPreset.adapter,
baseUrl: laterCleaned.url,
model: laterModel,
envKey: laterEnvKeyValid ? laterEnvKeyRaw : null,
keyPresent: laterKeyPresent,
keyRequired: laterKeyRequired,
maxStateTokens: laterPreset.defaultStateTokens ?? laterPreset.maxStateTokens,
maxChoiceOptions: laterPreset.maxChoiceOptions,
calibrated: laterPreset.calibrated,
inputPriceUsdPerMtok: laterPreset.inputPriceUsdPerMtok,
outputPriceUsdPerMtok: null,
thresholdProfile: laterPreset.thresholdProfile,
licenceNote: laterPreset.licenceNote,
processor: laterPreset.processor,
uses: laterHeld.uses,
shadowOnlyUses: laterHeld.shadowOnly,
});
}
const providers = Object.freeze([firstEntry, ...laterEntries]);
// An entry without its key is not configured: it is skipped at call
// time, and the feature is only off when NO entry is configured.
const anyConfigured = providers.some((p) => p.keyPresent || !p.keyRequired);
if (anyConfigured) {
for (const p of providers) {
if (!p.keyPresent && p.keyRequired) {
notes.push(
`decision_model_providers: provider '${p.name}' has no key in ` +
`${p.envKey ?? "its key variable"}; it is skipped until the variable is set`,
);
}
}
}
let status: DecisionModelStatus;
if (errors.length > 0) status = "invalid";
else if (!anyConfigured) status = "no_key";
else if (opts.vault !== null && (opts.vaultOptOut ?? defaultVaultOptOut)(opts.vault)) {
status = "disabled_by_vault";
} else status = "active";
return Object.freeze({
status,
errors: Object.freeze(errors),
notes: Object.freeze(notes),
enabled: true,
provider: primaryName,
providers,
adapter: firstEntry.adapter,
baseUrl,
model,
envKey,
keyPresent,
keyRequired,
allowInsecureHttp,
timeoutMs,
hookBudgetMs,
maxStateTokens,
maxChoiceOptions: firstEntry.maxChoiceOptions,
uses,
configuredUses: configured,
privateHostedUses,
dailyCostGateUsd,
inputPriceUsdPerMtok,
outputPriceUsdPerMtok,
allowUncalibrated,
calibrated,
thresholdProfile,
shadowOnlyUses: held.shadowOnly,
licenceNote: firstEntry.licenceNote,
processor: firstEntry.processor,
vault: opts.vault,
thresholdsPath: thresholdsPathFor(opts),
});
}
/**
* The mode a use runs in. Anything but an `active` configuration is `off`,
* whatever `decision_model_uses` says.
*/
export function decisionModelModeFor(
cfg: ResolvedDecisionModelConfig | null | undefined,
use: DecisionModelUse,
): DecisionModelMode {
if (cfg === null || cfg === undefined || cfg.status !== "active") return "off";
return cfg.uses[use];
}