@ai-matrx/agents 0.59.189 → 0.59.191

package/CHANGELOG.md

@@ -1,9 +1,21 @@
 # Changelog
 
+## 0.59.191
+### THE model-settings panel (2026-10-21)
+
+- Added `./settings/react` `ModelSettingsPanel`, `ExtraSettingRow`, `SettingRowFrame`, `SettingsGroupSection`, `SettingRowLabel`, `formatSettingValue`; `./settings` `SettingsWriteTarget` / `CapabilitiesWriteTarget` / `SettingRowRead`, `isOffValue` / `offValueFor` / `settingStateOf` / `withSettingState` / `ENUM_OFF_VALUE`, `isUnsetChoice` / `AUTO_VALUE` / `AUTO_MEANS_UNSET_KEYS`, `startingValueFor`.
+- Removed `SettingControlInput` props `size` and `explicitState`; `InputCapabilitiesEditor` prop `variant` (and `overriddenKeys` is now `changedKeys`); `ENUM_OFF_VALUE` is exported from `./settings` only.
+- **Consumer action:** render settings through `ModelSettingsPanel` with a `SettingsWriteTarget` (never `SettingControlInput` in a hand-built row); import the auto rule from `@ai-matrx/agents/settings` (the `@ai-matrx/chat/.../instance-model-overrides/auto-means-unset` module is gone); matrx-frontend deletes its `settings-management/setting-state.ts` and imports it from `@ai-matrx/agents/settings`.
+
+## 0.59.190
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 950fa97924 db501b9913 -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
 ## 0.59.189
 
-UNVERIFIED: this release has no Unreleased entry and the source comparison could not be made (the caller supplied no source comparison). Whether source changed is unknown; consumer action is unknown.
-Check the package's gitHead on npm against this version's gitHead: `git diff <previous gitHead> <this gitHead> -- apps/shared/matrx-agents/src`.
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 27c653019f 950fa97924 -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
 
 ## 0.59.188
 

package/dist/content-transfer/index.cjs

@@ -703,7 +703,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.189 — no longer declared in
+   * @deprecated retiring since 0.59.191 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */

package/dist/content-transfer/index.js

@@ -680,7 +680,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.189 — no longer declared in
+   * @deprecated retiring since 0.59.191 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */

package/dist/content-transfer/react/index.cjs

@@ -656,7 +656,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.189 — no longer declared in
+   * @deprecated retiring since 0.59.191 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */

package/dist/content-transfer/react/index.js

@@ -628,7 +628,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.189 — no longer declared in
+   * @deprecated retiring since 0.59.191 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */

package/dist/mandates/index.cjs

@@ -47,9 +47,9 @@ module.exports = __toCommonJS(mandates_exports);
 
 // mandates/keys.generated.ts
 var MANDATE_KEYS_META = {
-  aidreamRevision: "950fa979248f80022e27868d700b508553ddd9d5",
+  aidreamRevision: "89bae1f6f7736d73868dd44406d583d8a4e1ee49",
   generatorVersion: "1.0.0",
-  packageVersion: "0.59.189",
+  packageVersion: "0.59.191",
   retireWindow: 3
 };
 var MANDATE_KEYS = {
@@ -666,7 +666,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.189 — no longer declared in
+   * @deprecated retiring since 0.59.191 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */
@@ -693,7 +693,7 @@ var MANDATE_KEYS = {
 var ALL_MANDATE_KEYS = Object.values(MANDATE_KEYS);
 var RETIRING_MANDATE_KEYS = {
   "brand_discovery.offering_roles": "0.59.0",
-  "coding_session.managed_translation_reference": "0.59.189",
+  "coding_session.managed_translation_reference": "0.59.191",
   "pdf.content_cleaner": "0.59.0",
   "sms.owner_beta": "0.59.0",
   "voice.owner_beta": "0.59.0"

package/dist/mandates/index.d.cts

@@ -6,9 +6,9 @@
  * from the IN-PROCESS mandate declarations — the same `declared_mandates()` the
  * boot sync writes to the database from. There is no hand list anywhere.
  *
- * aidream revision:   950fa979248f80022e27868d700b508553ddd9d5
+ * aidream revision:   89bae1f6f7736d73868dd44406d583d8a4e1ee49
  * generator version:  1.0.0
- * package version:    0.59.189
+ * package version:    0.59.191
  * active keys:        606
  * retiring keys:      5
  *
@@ -19,9 +19,9 @@
  */
 /** Where this module came from — surfaced so a report can name the exact build. */
 declare const MANDATE_KEYS_META: {
-    readonly aidreamRevision: "950fa979248f80022e27868d700b508553ddd9d5";
+    readonly aidreamRevision: "89bae1f6f7736d73868dd44406d583d8a4e1ee49";
     readonly generatorVersion: "1.0.0";
-    readonly packageVersion: "0.59.189";
+    readonly packageVersion: "0.59.191";
     readonly retireWindow: 3;
 };
 /** Every declared mandate key, by THE IDENTIFIER RULE. */
@@ -639,7 +639,7 @@ declare const MANDATE_KEYS: {
      */
     readonly brand_discovery__offering_roles: "brand_discovery.offering_roles";
     /**
-     * @deprecated retiring since 0.59.189 — no longer declared in
+     * @deprecated retiring since 0.59.191 — no longer declared in
      * aidream. It leaves this union once no snapshot within the last
      * 3 published versions still carries it as active.
      */
@@ -670,7 +670,7 @@ declare const ALL_MANDATE_KEYS: readonly MandateKey[];
 /** Keys still in the union but no longer declared (two-phase retire, phase 1). */
 declare const RETIRING_MANDATE_KEYS: {
     readonly "brand_discovery.offering_roles": "0.59.0";
-    readonly "coding_session.managed_translation_reference": "0.59.189";
+    readonly "coding_session.managed_translation_reference": "0.59.191";
     readonly "pdf.content_cleaner": "0.59.0";
     readonly "sms.owner_beta": "0.59.0";
     readonly "voice.owner_beta": "0.59.0";

package/dist/mandates/index.d.ts

@@ -6,9 +6,9 @@
  * from the IN-PROCESS mandate declarations — the same `declared_mandates()` the
  * boot sync writes to the database from. There is no hand list anywhere.
  *
- * aidream revision:   950fa979248f80022e27868d700b508553ddd9d5
+ * aidream revision:   89bae1f6f7736d73868dd44406d583d8a4e1ee49
  * generator version:  1.0.0
- * package version:    0.59.189
+ * package version:    0.59.191
  * active keys:        606
  * retiring keys:      5
  *
@@ -19,9 +19,9 @@
  */
 /** Where this module came from — surfaced so a report can name the exact build. */
 declare const MANDATE_KEYS_META: {
-    readonly aidreamRevision: "950fa979248f80022e27868d700b508553ddd9d5";
+    readonly aidreamRevision: "89bae1f6f7736d73868dd44406d583d8a4e1ee49";
     readonly generatorVersion: "1.0.0";
-    readonly packageVersion: "0.59.189";
+    readonly packageVersion: "0.59.191";
     readonly retireWindow: 3;
 };
 /** Every declared mandate key, by THE IDENTIFIER RULE. */
@@ -639,7 +639,7 @@ declare const MANDATE_KEYS: {
      */
     readonly brand_discovery__offering_roles: "brand_discovery.offering_roles";
     /**
-     * @deprecated retiring since 0.59.189 — no longer declared in
+     * @deprecated retiring since 0.59.191 — no longer declared in
      * aidream. It leaves this union once no snapshot within the last
      * 3 published versions still carries it as active.
      */
@@ -670,7 +670,7 @@ declare const ALL_MANDATE_KEYS: readonly MandateKey[];
 /** Keys still in the union but no longer declared (two-phase retire, phase 1). */
 declare const RETIRING_MANDATE_KEYS: {
     readonly "brand_discovery.offering_roles": "0.59.0";
-    readonly "coding_session.managed_translation_reference": "0.59.189";
+    readonly "coding_session.managed_translation_reference": "0.59.191";
     readonly "pdf.content_cleaner": "0.59.0";
     readonly "sms.owner_beta": "0.59.0";
     readonly "voice.owner_beta": "0.59.0";

package/dist/mandates/index.js

@@ -1,8 +1,8 @@
 // mandates/keys.generated.ts
 var MANDATE_KEYS_META = {
-  aidreamRevision: "950fa979248f80022e27868d700b508553ddd9d5",
+  aidreamRevision: "89bae1f6f7736d73868dd44406d583d8a4e1ee49",
   generatorVersion: "1.0.0",
-  packageVersion: "0.59.189",
+  packageVersion: "0.59.191",
   retireWindow: 3
 };
 var MANDATE_KEYS = {
@@ -619,7 +619,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.189 — no longer declared in
+   * @deprecated retiring since 0.59.191 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */
@@ -646,7 +646,7 @@ var MANDATE_KEYS = {
 var ALL_MANDATE_KEYS = Object.values(MANDATE_KEYS);
 var RETIRING_MANDATE_KEYS = {
   "brand_discovery.offering_roles": "0.59.0",
-  "coding_session.managed_translation_reference": "0.59.189",
+  "coding_session.managed_translation_reference": "0.59.191",
   "pdf.content_cleaner": "0.59.0",
   "sms.owner_beta": "0.59.0",
   "voice.owner_beta": "0.59.0"

package/dist/settings/index.cjs

@@ -20,8 +20,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // settings/index.ts
 var settings_exports = {};
 __export(settings_exports, {
+  AUTO_MEANS_UNSET_KEYS: () => AUTO_MEANS_UNSET_KEYS,
+  AUTO_VALUE: () => AUTO_VALUE,
   CATALOGUE_KEYS: () => CATALOGUE_KEYS,
   EMPTY_UI_GATES: () => EMPTY_UI_GATES,
+  ENUM_OFF_VALUE: () => ENUM_OFF_VALUE,
   PARAM_ALIASES: () => PARAM_ALIASES,
   SETTINGS_CATALOGUE: () => SETTINGS_CATALOGUE,
   UI_GATE_EDITABLE_KEYS: () => UI_GATE_EDITABLE_KEYS,
@@ -35,9 +38,12 @@ __export(settings_exports, {
   extractModelDefaults: () => extractModelDefaults,
   gateEnabled: () => gateEnabled,
   getActionForMode: () => getActionForMode,
+  isOffValue: () => isOffValue,
   isUiGateKey: () => isUiGateKey,
+  isUnsetChoice: () => isUnsetChoice,
   mergeEffectiveSettings: () => mergeEffectiveSettings,
   mergeVariableValues: () => mergeVariableValues,
+  offValueFor: () => offValueFor,
   parseModelControls: () => parseModelControls,
   parseUiGates: () => parseUiGates,
   readApiPayload: () => readApiPayload,
@@ -49,7 +55,10 @@ __export(settings_exports, {
   readPreviewedResolution: () => readPreviewedResolution,
   readSettingsEntry: () => readSettingsEntry,
   resolveConflicts: () => resolveConflicts,
-  sanitizeSettings: () => sanitizeSettings
+  sanitizeSettings: () => sanitizeSettings,
+  settingStateOf: () => settingStateOf,
+  startingValueFor: () => startingValueFor,
+  withSettingState: () => withSettingState
 });
 module.exports = __toCommonJS(settings_exports);
 
@@ -947,3 +956,78 @@ function readConflictSummary(entry) {
 function readEffectiveVariableValues(entry) {
   return entry ? mergeVariableValues(entry.variable_defaults, entry.variable_overrides) : {};
 }
+
+// settings/setting-state.ts
+var ENUM_OFF_VALUE = "none";
+function offValueFor(control) {
+  if (!control) return void 0;
+  if (control.type === "boolean") return false;
+  if (control.type === "enum" && control.enum?.includes(ENUM_OFF_VALUE)) {
+    return ENUM_OFF_VALUE;
+  }
+  return void 0;
+}
+function isOffValue(value, control) {
+  if (value === false) return true;
+  if (value === ENUM_OFF_VALUE) {
+    return !control || control.type === "enum";
+  }
+  return false;
+}
+function settingStateOf(settings, key, control) {
+  const value = settings?.[key];
+  if (value === void 0 || value === null) return "unset";
+  return isOffValue(value, control) ? "off" : "value";
+}
+function withSettingState(settings, key, state, control, value) {
+  if (state === "unset") {
+    const { [key]: _removed, ...rest } = settings;
+    return rest;
+  }
+  if (state === "off") {
+    const off = offValueFor(control);
+    if (off === void 0) return settings;
+    return { ...settings, [key]: off };
+  }
+  if (value === void 0 || value === null) {
+    const { [key]: _removed, ...rest } = settings;
+    return rest;
+  }
+  return { ...settings, [key]: value };
+}
+
+// settings/auto-means-unset.ts
+var AUTO_VALUE = "auto";
+var AUTO_MEANS_UNSET_KEYS = /* @__PURE__ */ new Set([
+  "reasoning_effort",
+  "visualization"
+]);
+function isUnsetChoice(key, value) {
+  if (value === void 0 || value === null) return true;
+  return value === AUTO_VALUE && AUTO_MEANS_UNSET_KEYS.has(key);
+}
+
+// settings/starting-value.ts
+function startingValueFor(key, control) {
+  let value = control.default;
+  if (value === null || value === void 0) {
+    if (control.type === "number" || control.type === "integer") {
+      value = control.min ?? 0;
+    } else if (control.type === "string" || control.type === "string_array") {
+      value = "";
+    } else if (control.type === "boolean") {
+      value = false;
+    } else if (control.type === "enum" && control.enum?.length) {
+      value = control.enum[0];
+    } else if (control.type === "array" || control.type === "object_array") {
+      value = [];
+    }
+  }
+  if (isUnsetChoice(key, value) && control.type === "enum" && control.enum?.length) {
+    value = control.enum.find((choice) => !isUnsetChoice(key, choice));
+  }
+  if (key === "response_format" && typeof value === "string") {
+    value = value === "" ? void 0 : { type: value };
+  }
+  return value;
+}

package/dist/settings/index.d.cts

@@ -450,4 +450,162 @@ declare function readConflictSummary(entry: AgentSettingsEntry | undefined): Con
 /** Variable values the run sends: defaults with the person's overrides on top. */
 declare function readEffectiveVariableValues(entry: AgentSettingsEntry | undefined): Record<string, string>;
 
-export { type AgentContext, type AgentSettings, type AgentSettingsEntry, type AgentSettingsState, type AgentSource, type AgentVariable, CATALOGUE_KEYS, type CatalogueEntry, type CatalogueGroup, type ConflictAction, type ConflictItem, type ConflictReason, type ConflictSummary, type ControlDefinition, type ControlType, EMPTY_UI_GATES, type InitializeSettingsInput, type LLMParams, type NormalizedControls, PARAM_ALIASES, type PendingModelSwitch, type RenderGroup, type ResolutionMode, SETTINGS_CATALOGUE, type SettingsGroupId, type SettingsModelInfo, type SettingsRow, type SettingsStore, type SettingsStoreConfig, UI_GATE_EDITABLE_KEYS, UI_GATE_KEYS, type UiGateEditableKey, type UiGateKey, type UiGates, type VariableCustomComponentRef, buildApiPayload, buildSettingsRows, computeOverrideDiff, createSettingsStore, detectConflicts, effectiveOfferingPinOf, extractModelDefaults, gateEnabled, getActionForMode, isUiGateKey, mergeEffectiveSettings, mergeVariableValues, parseModelControls, parseUiGates, readApiPayload, readConflictActions, readConflictSummary, readEffectiveModelId, readEffectiveSettings, readEffectiveVariableValues, readPreviewedResolution, readSettingsEntry, resolveConflicts, sanitizeSettings };
+/**
+ * The three states of one model setting — THE definition every settings
+ * surface reads (owner, 2026-10-02: "the difference between something being
+ * set to none and something not being included at all").
+ *
+ *   unset — the key is ABSENT from the saved settings JSON. The model's own
+ *           default applies. A person can always return a setting here.
+ *   off   — an explicit off value is saved: `false` for a boolean control,
+ *           `"none"` for an enum control that declares it (reasoning_effort,
+ *           thinking_level, …). The server translates it per model (K6 `off`
+ *           in common-docs/projects/settings-translation/CONTRACTS.md) — it is
+ *           never the same request as unset.
+ *   value — any other saved value.
+ *
+ * `null` in the saved JSON is treated as unset, and writing unset DELETES the
+ * key — the client never stores `null` (or a sentinel like `-1`) to mean
+ * "not set".
+ */
+
+type SettingState = "unset" | "off" | "value";
+/** The enum value that means "off" when a control declares it. */
+declare const ENUM_OFF_VALUE = "none";
+/**
+ * The explicit off value this control can save, or `undefined` when the
+ * setting has no off (e.g. temperature — 0 is a value, not off).
+ */
+declare function offValueFor(control: ControlDefinition | null | undefined): boolean | string | undefined;
+/** True when `value` is an explicit off (boolean false or enum "none"). */
+declare function isOffValue(value: unknown, control: ControlDefinition | null | undefined): boolean;
+declare function settingStateOf(settings: Record<string, unknown> | null | undefined, key: string, control: ControlDefinition | null | undefined): SettingState;
+/**
+ * Write one setting into a NEW settings object.
+ *   unset → the key is removed (never `null`)
+ *   off   → the control's off value (no-op when the control has none)
+ *   value → `value`
+ */
+declare function withSettingState<T extends Record<string, unknown>>(settings: T, key: string, state: SettingState, control: ControlDefinition | null | undefined, value?: unknown): T;
+
+/**
+ * ONE MEANING PER STATE (settings-translation F-b, owner 2026-10-02: "the
+ * difference between something being set to none and something not being
+ * included at all").
+ *
+ * For these keys the house "auto" posture IS the unset state on the server:
+ *   - reasoning_effort — aidream `matrx_ai/catalog/canonicalize.py` normalizes
+ *     "auto" to None before any rule or processor sees it (ai_041).
+ *   - visualization — the Google research agent reads an unset value as "auto"
+ *     (`providers/google/google_research_agent.py`).
+ * So a control that offers "auto" for one of them must CLEAR the key, never
+ * save the word: a saved "auto" and an absent key would be two stored states
+ * with one meaning. Keys whose "auto" is a real provider value that goes on the
+ * wire (render_quality, background, moderation, reasoning_summary) are NOT here.
+ *
+ * Every settings writer reads this one rule: the agent builder
+ * (AgentSettingsCore), the conversation settings target (useConversationSettingsTarget), the
+ * comparison column editor, and the wire selector.
+ */
+declare const AUTO_VALUE = "auto";
+declare const AUTO_MEANS_UNSET_KEYS: ReadonlySet<string>;
+/** True when writing `value` to `key` means "not set" — the key is removed. */
+declare function isUnsetChoice(key: string, value: unknown): boolean;
+
+/**
+ * THE starting value of a setting a person turns on (ticks its box). One rule
+ * for every settings writer — the agent builder and every conversation /
+ * binding override — so ticking "Max Output Tokens" stores the same value
+ * wherever it is ticked.
+ *
+ *   - the model's declared default when it has one,
+ *   - otherwise the control's natural empty value (min / "" / false / first
+ *     choice / []),
+ *   - never a choice that IS "not set" ("auto" effort): ticking SETS the
+ *     setting, so the first real choice is taken instead,
+ *   - `response_format` is stored in its canonical `{ type }` shape.
+ *
+ * `undefined` means nothing can be stored — the box stays unticked rather than
+ * claiming a setting that does not exist.
+ */
+
+declare function startingValueFor(key: string, control: ControlDefinition): unknown;
+
+/**
+ * THE SETTINGS WRITE TARGET — the one seam between THE model-settings panel
+ * (`./react/ModelSettingsPanel`) and whatever a change is written to.
+ *
+ * Owner ruling, 2026-10-21: one settings experience. The agent builder and the
+ * chat's "Model and overrides" render the SAME rows, controls, labels and
+ * order; they differ ONLY in where a change lands. The builder's target writes
+ * the agent; a conversation's (or a binding's, a mandate's, a shortcut's)
+ * target writes that record's overrides and adds a per-row reset back to what
+ * it inherits. The panel never knows which.
+ *
+ * Every method is the person's intent in the panel's words — never a store
+ * action. Optional methods are optional ACTIONS: a target that cannot bind a
+ * control to a run input simply has no `bind`, and the panel draws no button.
+ */
+
+/** What one row shows. Off is a `set` value the panel recognizes (setting-state). */
+type SettingRowView = 
+/** Key absent: the model's own default applies. */
+{
+    state: "unset";
+    modelDefault?: unknown;
+}
+/** A saved / effective value. */
+ | {
+    state: "set";
+    value: unknown;
+}
+/** The setting is a run input: its value comes from `{{variableName}}`. */
+ | {
+    state: "bound";
+    variableName: string;
+    value: unknown;
+};
+/** What the target knows about a row beyond its value. */
+interface SettingRowFacts {
+    /** True when THIS target changed the row (a conversation override). */
+    changedHere?: boolean;
+    /** Where the shown value comes from, in the host's words ("Agent", "Organization"). */
+    source?: string;
+    /** The row's first validation issue, when the target validates. */
+    issue?: {
+        message: string;
+        fixable: boolean;
+    };
+}
+type SettingRowRead = SettingRowView & SettingRowFacts;
+interface SettingsWriteTarget {
+    read(key: string, control: ControlDefinition | null): SettingRowRead;
+    /** The person edited the control. */
+    change(key: string, value: unknown, control: ControlDefinition | null): void;
+    /** The person ticked an unset row (store `startingValueFor`). */
+    turnOn(key: string, control: ControlDefinition): void;
+    /** The person cleared the row back to "not set". */
+    clear(key: string): void;
+    /** One-click repair of the row's issue. */
+    fix?(key: string): void;
+    /** May this row become a run input? (Builder only.) */
+    canBind?(key: string): boolean;
+    bind?(key: string, control: ControlDefinition): void;
+    unbind?(key: string, control: ControlDefinition | null): void;
+    /** Drop THIS target's change and show what it inherits again. */
+    resetToInherited?(key: string): void;
+    /** The reset button's words, in the host's noun. Default "Reset to agent". */
+    resetLabel?: string;
+}
+/** The frontend input capabilities (ui gates) shown under the settings groups. */
+interface CapabilitiesWriteTarget {
+    values: UiGates;
+    change(key: UiGateEditableKey, value: boolean): void;
+    /** Keys THIS target changed; each gets its own reset. */
+    changedKeys?: ReadonlySet<UiGateEditableKey>;
+    resetToInherited?(key: UiGateEditableKey): void;
+    /** Said under the rows when saving the capabilities failed. */
+    error?: string | null;
+}
+
+export { AUTO_MEANS_UNSET_KEYS, AUTO_VALUE, type AgentContext, type AgentSettings, type AgentSettingsEntry, type AgentSettingsState, type AgentSource, type AgentVariable, CATALOGUE_KEYS, type CapabilitiesWriteTarget, type CatalogueEntry, type CatalogueGroup, type ConflictAction, type ConflictItem, type ConflictReason, type ConflictSummary, type ControlDefinition, type ControlType, EMPTY_UI_GATES, ENUM_OFF_VALUE, type InitializeSettingsInput, type LLMParams, type NormalizedControls, PARAM_ALIASES, type PendingModelSwitch, type RenderGroup, type ResolutionMode, SETTINGS_CATALOGUE, type SettingRowFacts, type SettingRowRead, type SettingRowView, type SettingState, type SettingsGroupId, type SettingsModelInfo, type SettingsRow, type SettingsStore, type SettingsStoreConfig, type SettingsWriteTarget, UI_GATE_EDITABLE_KEYS, UI_GATE_KEYS, type UiGateEditableKey, type UiGateKey, type UiGates, type VariableCustomComponentRef, buildApiPayload, buildSettingsRows, computeOverrideDiff, createSettingsStore, detectConflicts, effectiveOfferingPinOf, extractModelDefaults, gateEnabled, getActionForMode, isOffValue, isUiGateKey, isUnsetChoice, mergeEffectiveSettings, mergeVariableValues, offValueFor, parseModelControls, parseUiGates, readApiPayload, readConflictActions, readConflictSummary, readEffectiveModelId, readEffectiveSettings, readEffectiveVariableValues, readPreviewedResolution, readSettingsEntry, resolveConflicts, sanitizeSettings, settingStateOf, startingValueFor, withSettingState };

package/dist/settings/index.d.ts

@@ -450,4 +450,162 @@ declare function readConflictSummary(entry: AgentSettingsEntry | undefined): Con
 /** Variable values the run sends: defaults with the person's overrides on top. */
 declare function readEffectiveVariableValues(entry: AgentSettingsEntry | undefined): Record<string, string>;
 
-export { type AgentContext, type AgentSettings, type AgentSettingsEntry, type AgentSettingsState, type AgentSource, type AgentVariable, CATALOGUE_KEYS, type CatalogueEntry, type CatalogueGroup, type ConflictAction, type ConflictItem, type ConflictReason, type ConflictSummary, type ControlDefinition, type ControlType, EMPTY_UI_GATES, type InitializeSettingsInput, type LLMParams, type NormalizedControls, PARAM_ALIASES, type PendingModelSwitch, type RenderGroup, type ResolutionMode, SETTINGS_CATALOGUE, type SettingsGroupId, type SettingsModelInfo, type SettingsRow, type SettingsStore, type SettingsStoreConfig, UI_GATE_EDITABLE_KEYS, UI_GATE_KEYS, type UiGateEditableKey, type UiGateKey, type UiGates, type VariableCustomComponentRef, buildApiPayload, buildSettingsRows, computeOverrideDiff, createSettingsStore, detectConflicts, effectiveOfferingPinOf, extractModelDefaults, gateEnabled, getActionForMode, isUiGateKey, mergeEffectiveSettings, mergeVariableValues, parseModelControls, parseUiGates, readApiPayload, readConflictActions, readConflictSummary, readEffectiveModelId, readEffectiveSettings, readEffectiveVariableValues, readPreviewedResolution, readSettingsEntry, resolveConflicts, sanitizeSettings };
+/**
+ * The three states of one model setting — THE definition every settings
+ * surface reads (owner, 2026-10-02: "the difference between something being
+ * set to none and something not being included at all").
+ *
+ *   unset — the key is ABSENT from the saved settings JSON. The model's own
+ *           default applies. A person can always return a setting here.
+ *   off   — an explicit off value is saved: `false` for a boolean control,
+ *           `"none"` for an enum control that declares it (reasoning_effort,
+ *           thinking_level, …). The server translates it per model (K6 `off`
+ *           in common-docs/projects/settings-translation/CONTRACTS.md) — it is
+ *           never the same request as unset.
+ *   value — any other saved value.
+ *
+ * `null` in the saved JSON is treated as unset, and writing unset DELETES the
+ * key — the client never stores `null` (or a sentinel like `-1`) to mean
+ * "not set".
+ */
+
+type SettingState = "unset" | "off" | "value";
+/** The enum value that means "off" when a control declares it. */
+declare const ENUM_OFF_VALUE = "none";
+/**
+ * The explicit off value this control can save, or `undefined` when the
+ * setting has no off (e.g. temperature — 0 is a value, not off).
+ */
+declare function offValueFor(control: ControlDefinition | null | undefined): boolean | string | undefined;
+/** True when `value` is an explicit off (boolean false or enum "none"). */
+declare function isOffValue(value: unknown, control: ControlDefinition | null | undefined): boolean;
+declare function settingStateOf(settings: Record<string, unknown> | null | undefined, key: string, control: ControlDefinition | null | undefined): SettingState;
+/**
+ * Write one setting into a NEW settings object.
+ *   unset → the key is removed (never `null`)
+ *   off   → the control's off value (no-op when the control has none)
+ *   value → `value`
+ */
+declare function withSettingState<T extends Record<string, unknown>>(settings: T, key: string, state: SettingState, control: ControlDefinition | null | undefined, value?: unknown): T;
+
+/**
+ * ONE MEANING PER STATE (settings-translation F-b, owner 2026-10-02: "the
+ * difference between something being set to none and something not being
+ * included at all").
+ *
+ * For these keys the house "auto" posture IS the unset state on the server:
+ *   - reasoning_effort — aidream `matrx_ai/catalog/canonicalize.py` normalizes
+ *     "auto" to None before any rule or processor sees it (ai_041).
+ *   - visualization — the Google research agent reads an unset value as "auto"
+ *     (`providers/google/google_research_agent.py`).
+ * So a control that offers "auto" for one of them must CLEAR the key, never
+ * save the word: a saved "auto" and an absent key would be two stored states
+ * with one meaning. Keys whose "auto" is a real provider value that goes on the
+ * wire (render_quality, background, moderation, reasoning_summary) are NOT here.
+ *
+ * Every settings writer reads this one rule: the agent builder
+ * (AgentSettingsCore), the conversation settings target (useConversationSettingsTarget), the
+ * comparison column editor, and the wire selector.
+ */
+declare const AUTO_VALUE = "auto";
+declare const AUTO_MEANS_UNSET_KEYS: ReadonlySet<string>;
+/** True when writing `value` to `key` means "not set" — the key is removed. */
+declare function isUnsetChoice(key: string, value: unknown): boolean;
+
+/**
+ * THE starting value of a setting a person turns on (ticks its box). One rule
+ * for every settings writer — the agent builder and every conversation /
+ * binding override — so ticking "Max Output Tokens" stores the same value
+ * wherever it is ticked.
+ *
+ *   - the model's declared default when it has one,
+ *   - otherwise the control's natural empty value (min / "" / false / first
+ *     choice / []),
+ *   - never a choice that IS "not set" ("auto" effort): ticking SETS the
+ *     setting, so the first real choice is taken instead,
+ *   - `response_format` is stored in its canonical `{ type }` shape.
+ *
+ * `undefined` means nothing can be stored — the box stays unticked rather than
+ * claiming a setting that does not exist.
+ */
+
+declare function startingValueFor(key: string, control: ControlDefinition): unknown;
+
+/**
+ * THE SETTINGS WRITE TARGET — the one seam between THE model-settings panel
+ * (`./react/ModelSettingsPanel`) and whatever a change is written to.
+ *
+ * Owner ruling, 2026-10-21: one settings experience. The agent builder and the
+ * chat's "Model and overrides" render the SAME rows, controls, labels and
+ * order; they differ ONLY in where a change lands. The builder's target writes
+ * the agent; a conversation's (or a binding's, a mandate's, a shortcut's)
+ * target writes that record's overrides and adds a per-row reset back to what
+ * it inherits. The panel never knows which.
+ *
+ * Every method is the person's intent in the panel's words — never a store
+ * action. Optional methods are optional ACTIONS: a target that cannot bind a
+ * control to a run input simply has no `bind`, and the panel draws no button.
+ */
+
+/** What one row shows. Off is a `set` value the panel recognizes (setting-state). */
+type SettingRowView = 
+/** Key absent: the model's own default applies. */
+{
+    state: "unset";
+    modelDefault?: unknown;
+}
+/** A saved / effective value. */
+ | {
+    state: "set";
+    value: unknown;
+}
+/** The setting is a run input: its value comes from `{{variableName}}`. */
+ | {
+    state: "bound";
+    variableName: string;
+    value: unknown;
+};
+/** What the target knows about a row beyond its value. */
+interface SettingRowFacts {
+    /** True when THIS target changed the row (a conversation override). */
+    changedHere?: boolean;
+    /** Where the shown value comes from, in the host's words ("Agent", "Organization"). */
+    source?: string;
+    /** The row's first validation issue, when the target validates. */
+    issue?: {
+        message: string;
+        fixable: boolean;
+    };
+}
+type SettingRowRead = SettingRowView & SettingRowFacts;
+interface SettingsWriteTarget {
+    read(key: string, control: ControlDefinition | null): SettingRowRead;
+    /** The person edited the control. */
+    change(key: string, value: unknown, control: ControlDefinition | null): void;
+    /** The person ticked an unset row (store `startingValueFor`). */
+    turnOn(key: string, control: ControlDefinition): void;
+    /** The person cleared the row back to "not set". */
+    clear(key: string): void;
+    /** One-click repair of the row's issue. */
+    fix?(key: string): void;
+    /** May this row become a run input? (Builder only.) */
+    canBind?(key: string): boolean;
+    bind?(key: string, control: ControlDefinition): void;
+    unbind?(key: string, control: ControlDefinition | null): void;
+    /** Drop THIS target's change and show what it inherits again. */
+    resetToInherited?(key: string): void;
+    /** The reset button's words, in the host's noun. Default "Reset to agent". */
+    resetLabel?: string;
+}
+/** The frontend input capabilities (ui gates) shown under the settings groups. */
+interface CapabilitiesWriteTarget {
+    values: UiGates;
+    change(key: UiGateEditableKey, value: boolean): void;
+    /** Keys THIS target changed; each gets its own reset. */
+    changedKeys?: ReadonlySet<UiGateEditableKey>;
+    resetToInherited?(key: UiGateEditableKey): void;
+    /** Said under the rows when saving the capabilities failed. */
+    error?: string | null;
+}
+
+export { AUTO_MEANS_UNSET_KEYS, AUTO_VALUE, type AgentContext, type AgentSettings, type AgentSettingsEntry, type AgentSettingsState, type AgentSource, type AgentVariable, CATALOGUE_KEYS, type CapabilitiesWriteTarget, type CatalogueEntry, type CatalogueGroup, type ConflictAction, type ConflictItem, type ConflictReason, type ConflictSummary, type ControlDefinition, type ControlType, EMPTY_UI_GATES, ENUM_OFF_VALUE, type InitializeSettingsInput, type LLMParams, type NormalizedControls, PARAM_ALIASES, type PendingModelSwitch, type RenderGroup, type ResolutionMode, SETTINGS_CATALOGUE, type SettingRowFacts, type SettingRowRead, type SettingRowView, type SettingState, type SettingsGroupId, type SettingsModelInfo, type SettingsRow, type SettingsStore, type SettingsStoreConfig, type SettingsWriteTarget, UI_GATE_EDITABLE_KEYS, UI_GATE_KEYS, type UiGateEditableKey, type UiGateKey, type UiGates, type VariableCustomComponentRef, buildApiPayload, buildSettingsRows, computeOverrideDiff, createSettingsStore, detectConflicts, effectiveOfferingPinOf, extractModelDefaults, gateEnabled, getActionForMode, isOffValue, isUiGateKey, isUnsetChoice, mergeEffectiveSettings, mergeVariableValues, offValueFor, parseModelControls, parseUiGates, readApiPayload, readConflictActions, readConflictSummary, readEffectiveModelId, readEffectiveSettings, readEffectiveVariableValues, readPreviewedResolution, readSettingsEntry, resolveConflicts, sanitizeSettings, settingStateOf, startingValueFor, withSettingState };