@ai-matrx/chat 0.5.17 → 0.6.0

package/dist/agents/redux/agent-settings/internal-utils.d.ts

@@ -1,123 +1,2 @@
-/**
- * Agent Settings — Internal Utilities
- *
- * Pure functions with NO Redux imports. No React hooks.
- * All logic that was previously scattered across:
- *   - useModelControls hook
- *   - switchModel thunk
- *   - ModelChangeConflictModal component
- *   - ConversationInput.handleSettingsChange
- *
- * is consolidated here and consumed by the slice's reducers/thunks.
- */
-import type { AgentSettings, AgentVariable, ConflictAction, ConflictItem, NormalizedControls, PendingModelSwitch, ResolutionMode } from "./types.js";
-import { AgentContext } from "./types.js";
-export type { AgentContext };
-/**
- * Cross-provider parameter name synonyms.
- * When a setting key is unsupported by a new model, we check aliases
- * to suggest the equivalent parameter name the new model may use instead.
- */
-export declare const PARAM_ALIASES: Readonly<Record<string, string[]>>;
-/**
- * Parse raw JSONB controls from `ai_model.controls` into a typed NormalizedControls map.
- *
- * Absorbs the logic from `useModelControls` hook.
- *
- * Control JSONB shape per field:
- *   { type?, min?, max?, default?, enum?, required?, allowed? }
- *
- * Special cases:
- *   - `output_format` → `response_format` only for text response formats
- *     (outputFormatControlKey); an image file format keeps its own key
- *   - `allowed: true/false` → boolean feature flag
- *   - enum values that are `{ type: "json_object" }` objects → flattened to string
- */
-export declare function parseModelControls(rawControls: Record<string, unknown> | null | undefined): NormalizedControls;
-/**
- * Extract submission-ready default values from a model's raw controls JSONB.
- *
- * Absorbs the logic from `getModelDefaults` in `useModelControls`.
- *
- * Rules:
- *   - Controls with `default: null` are SKIPPED (opt-in only controls)
- *   - `tools: { allowed: true }` → `tools: []` (empty list, not a boolean)
- *   - `response_format: "text"` → SKIP (backend treats absence as text)
- *   - `response_format: "json_object"` → `{ type: "json_object" }` (dict form)
- *   - UI-only capability flags (image_urls, file_urls, etc.) → kept as booleans
- */
-export declare function extractModelDefaults(rawControls: Record<string, unknown> | null | undefined): Partial<AgentSettings>;
-/**
- * Detect which keys in `currentSettings` are incompatible with `newControls`.
- *
- * Returns:
- *   - `conflicts`: settings that have problems (unsupported, out-of-range, wrong enum)
- *   - `supportedKeys`: settings that carry over cleanly
- *
- * This is the NEW detection logic that was missing from the existing system
- * (the old ModelChangeConflictModal received conflicts pre-built from above).
- */
-export declare function detectConflicts(currentSettings: Partial<AgentSettings>, newControls: NormalizedControls, newDefaults: Partial<AgentSettings>): {
-    conflicts: ConflictItem[];
-    supportedKeys: Array<keyof AgentSettings>;
-};
-/**
- * Apply a pending switch's resolution mode + custom actions to produce
- * the final settings after the model change is confirmed.
- *
- * Absorbs `computeResolvedSettings` from ModelChangeConflictModal.
- */
-export declare function resolveConflicts(currentSettings: Partial<AgentSettings>, pending: PendingModelSwitch): Partial<AgentSettings>;
-/**
- * Determine the action ('keep' | 'reset') for a conflict given the current mode.
- * Absorbs `getActionForMode` from ModelChangeConflictModal.
- */
-export declare function getActionForMode(mode: ResolutionMode, conflict: ConflictItem, customActions: Partial<Record<keyof AgentSettings, ConflictAction>>): ConflictAction;
-/**
- * Compare `proposed` settings against `defaults` and return only the keys
- * that genuinely differ. Uses JSON-stringify for deep comparison.
- *
- * Absorbs the diff logic from ConversationInput.handleSettingsChange.
- * In chat/test contexts, only true overrides are stored — not redundant defaults.
- *
- * REMOVAL IS A DIFF TOO: a key the defaults carry that `proposed` dropped (or
- * set to null) is stored as an explicit `null` override. Without it a removal
- * was inexpressible — the default (e.g. the agent's class pin `offering_id`)
- * silently came back on the next merge and on the wire. `null` = "the API must
- * not use this key"; `mergeEffectiveSettings` deletes it, `buildApiPayload`
- * sends it (the server honours `offering_id: null`).
- */
-export declare function computeOverrideDiff(defaults: Partial<AgentSettings>, proposed: Partial<AgentSettings>): Partial<AgentSettings>;
-/**
- * The class pin (`offering_id`) an entry runs on: an override — including an
- * explicit `null` removal — wins over the defaults. Never `overrides ?? defaults`
- * (a removal is `null`, which `??` would fall through to the default's pin).
- */
-export declare function effectiveOfferingPinOf(entry: {
-    defaults?: Partial<AgentSettings>;
-    overrides?: Partial<AgentSettings>;
-} | null | undefined): string | undefined;
-/**
- * Build the payload to send to the Python backend for a given context.
- *
- * - 'builder': full effective settings minus UI-only flags
- * - 'chat': only the overrides delta minus UI-only flags
- *   (backend already has the agent's defaults — only send what changed)
- * - 'test': same as builder (full effective settings)
- */
-export declare function buildApiPayload(effectiveSettings: Partial<AgentSettings>, overrides: Partial<AgentSettings>, context: AgentContext): Partial<AgentSettings>;
-/**
- * Merge defaults + overrides into the effective settings the UI should display.
- * Overrides take precedence field-by-field.
- */
-export declare function mergeEffectiveSettings(defaults: Partial<AgentSettings>, overrides: Partial<AgentSettings>): Partial<AgentSettings>;
-/**
- * Produce a flat name→value map from variable_defaults merged with variable_overrides.
- * Used by variable input components to read current values without prop drilling.
- */
-export declare function mergeVariableValues(variableDefaults: AgentVariable[], variableOverrides: Record<string, string>): Record<string, string>;
-/**
- * Strip null/undefined fields from a settings object.
- * Used when loading from DB to ensure the state is clean.
- */
-export declare function sanitizeSettings(raw: Record<string, unknown> | null | undefined): Partial<AgentSettings>;
+/** Agent settings live in the agent core (B4): `@ai-matrx/agents/settings`. */
+export * from "@ai-matrx/agents/settings";

package/dist/agents/redux/agent-settings/internal-utils.js

@@ -1,315 +1 @@
-import { LLM_PARAMS_KEYS } from "@ai-matrx/agents/generated/llm-enums";
-import { outputFormatControlKey } from "@ai-matrx/agents/models";
-import { isUiGateKey, UI_GATE_KEYS } from "./ui-gates.js";
-const PARAM_ALIASES = {
-  max_tokens: ["max_output_tokens", "max_completion_tokens", "max_new_tokens"],
-  max_output_tokens: ["max_tokens", "max_completion_tokens", "max_new_tokens"],
-  max_completion_tokens: ["max_tokens", "max_output_tokens"],
-  max_new_tokens: ["max_tokens", "max_output_tokens"],
-  stop: ["stop_sequences"],
-  stop_sequences: ["stop"],
-  top_k: ["top_k_tokens"],
-  top_k_tokens: ["top_k"],
-  presence_penalty: ["repetition_penalty"],
-  repetition_penalty: ["presence_penalty"],
-  reasoning_budget: ["thinking_budget"],
-  thinking_budget: ["reasoning_budget"]
-};
-const ALL_KNOWN_KEYS = /* @__PURE__ */ new Set([
-  ...LLM_PARAMS_KEYS,
-  // Legacy DB keys — normalizer converts at Redux boundary, but we still recognize them
-  "max_tokens",
-  "output_format",
-  "n",
-  // Frontend-only capability flags (never sent to the API)
-  "tools",
-  "file_urls",
-  "image_urls",
-  "youtube_videos",
-  "multi_speaker",
-  "internal_web_search",
-  "internal_url_context",
-  // Backend param not yet in generated types
-  "image_loras",
-  // Stop sequences
-  "stop_sequences"
-]);
-function parseModelControls(rawControls) {
-  if (!rawControls || typeof rawControls !== "object" || Array.isArray(rawControls)) {
-    return { rawControls: {}, unmappedControls: {} };
-  }
-  let controls = rawControls;
-  const normalized = {
-    rawControls: controls,
-    unmappedControls: {}
-  };
-  for (const [key, value] of Object.entries(controls)) {
-    if (!ALL_KNOWN_KEYS.has(key)) {
-      normalized.unmappedControls[key] = value;
-      continue;
-    }
-    const normalizedKey = outputFormatControlKey(key, value);
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-      continue;
-    }
-    const rawControl = value;
-    const rawDefault = rawControl.default;
-    const flatDefault = rawDefault !== null && typeof rawDefault === "object" && !Array.isArray(rawDefault) && "type" in rawDefault ? String(rawDefault.type) : rawDefault;
-    const controlDef = {
-      type: rawControl.type || "string",
-      min: rawControl.min,
-      max: rawControl.max,
-      default: flatDefault,
-      required: rawControl.required
-    };
-    if (Array.isArray(rawControl.enum)) {
-      controlDef.enum = rawControl.enum.map((option) => {
-        if (option !== null && typeof option === "object" && "type" in option) {
-          return String(option.type);
-        }
-        return String(option);
-      });
-      controlDef.type = "enum";
-    } else if ("allowed" in rawControl) {
-      controlDef.type = "boolean";
-      controlDef.default = rawControl.allowed;
-      controlDef.isFeatureFlag = true;
-    } else if (typeof rawControl.default === "boolean") {
-      controlDef.type = "boolean";
-    } else if (rawControl.type === void 0 && (rawControl.min !== void 0 || rawControl.max !== void 0)) {
-      controlDef.type = rawControl.default !== void 0 && Number.isInteger(rawControl.default) ? "integer" : "number";
-    }
-    normalized[normalizedKey] = controlDef;
-  }
-  return normalized;
-}
-function extractModelDefaults(rawControls) {
-  if (!rawControls || typeof rawControls !== "object" || Array.isArray(rawControls)) {
-    return {};
-  }
-  const defaults = {};
-  for (const [key, value] of Object.entries(rawControls)) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-      continue;
-    }
-    const rawControl = value;
-    const normalizedKey = outputFormatControlKey(key, value);
-    if (isUiGateKey(normalizedKey)) {
-      if (normalizedKey === "tools") {
-        if (rawControl.allowed === true) {
-          defaults.tools = [];
-        }
-      } else {
-        const flagValue = "allowed" in rawControl ? rawControl.allowed : rawControl.default;
-        if (flagValue !== null && flagValue !== void 0) {
-          defaults[normalizedKey] = Boolean(flagValue);
-        }
-      }
-      continue;
-    }
-    let defaultValue;
-    if (rawControl.default !== void 0 && rawControl.default !== null) {
-      defaultValue = rawControl.default;
-    } else if ("allowed" in rawControl) {
-      defaultValue = rawControl.allowed;
-    } else if (Array.isArray(rawControl.enum) && rawControl.enum.length > 0 && rawControl.default === void 0) {
-      defaultValue = void 0;
-    }
-    if (defaultValue === void 0 || defaultValue === null) continue;
-    if (typeof defaultValue === "object" && !Array.isArray(defaultValue) && "type" in defaultValue) {
-      defaultValue = String(defaultValue.type);
-    }
-    if (normalizedKey === "response_format") {
-      if (typeof defaultValue === "string") {
-        if (defaultValue === "text" || defaultValue === "") continue;
-        defaults[normalizedKey] = { type: defaultValue };
-      } else {
-        defaults[normalizedKey] = defaultValue;
-      }
-      continue;
-    }
-    defaults[normalizedKey] = defaultValue;
-  }
-  return defaults;
-}
-function detectConflicts(currentSettings, newControls, newDefaults) {
-  const conflicts = [];
-  const supportedKeys = [];
-  const skipKeys = /* @__PURE__ */ new Set(["model", "offering_id"]);
-  for (const [rawKey, currentValue] of Object.entries(currentSettings)) {
-    const key = rawKey;
-    if (skipKeys.has(key)) continue;
-    if (currentValue === void 0 || currentValue === null) continue;
-    const controlDef = newControls[key];
-    if (!controlDef) {
-      const aliasHint = findAliasHint(key, newControls);
-      conflicts.push({
-        key,
-        currentValue,
-        newModelDefault: newDefaults[key] ?? null,
-        reason: "unsupported_key",
-        // Kept by default (keep_all): the server translates it for this model.
-        description: aliasHint ? `Translated for this model. Its own setting is "${aliasHint}".` : "Translated for this model.",
-        aliasHint: aliasHint ?? void 0
-      });
-      continue;
-    }
-    if ((controlDef.type === "number" || controlDef.type === "integer") && typeof currentValue === "number") {
-      const tooLow = controlDef.min !== void 0 && currentValue < controlDef.min;
-      const tooHigh = controlDef.max !== void 0 && currentValue > controlDef.max;
-      if (tooLow || tooHigh) {
-        const rangeStr = formatRange(controlDef);
-        conflicts.push({
-          key,
-          currentValue,
-          newModelDefault: newDefaults[key] ?? controlDef.default ?? null,
-          reason: "value_out_of_range",
-          description: `Value ${currentValue} is outside the supported range ${rangeStr}.`
-        });
-        continue;
-      }
-    }
-    if (controlDef.type === "enum" && Array.isArray(controlDef.enum) && typeof currentValue === "string") {
-      if (!controlDef.enum.includes(currentValue)) {
-        conflicts.push({
-          key,
-          currentValue,
-          newModelDefault: newDefaults[key] ?? controlDef.default ?? null,
-          reason: "invalid_enum_value",
-          description: `"${currentValue}" is not valid for this model. Supported: ${controlDef.enum.join(", ")}.`
-        });
-        continue;
-      }
-    }
-    supportedKeys.push(key);
-  }
-  return { conflicts, supportedKeys };
-}
-function findAliasHint(key, controls) {
-  const aliases = PARAM_ALIASES[key];
-  if (!aliases) return null;
-  return aliases.find(
-    (alias) => controls[alias] !== void 0
-  ) ?? null;
-}
-function formatRange(def) {
-  if (def.min !== void 0 && def.max !== void 0) {
-    return `[${def.min}, ${def.max}]`;
-  }
-  if (def.min !== void 0) return `[${def.min}, \u221E)`;
-  if (def.max !== void 0) return `(-\u221E, ${def.max}]`;
-  return "(unbounded)";
-}
-function resolveConflicts(currentSettings, pending) {
-  const resolved = { ...currentSettings };
-  for (const conflict of pending.conflicts) {
-    const action = getActionForMode(
-      pending.mode,
-      conflict,
-      pending.customActions
-    );
-    if (action === "reset") {
-      if (conflict.reason !== "unsupported_key" && conflict.newModelDefault !== void 0 && conflict.newModelDefault !== null) {
-        resolved[conflict.key] = conflict.newModelDefault;
-      } else {
-        delete resolved[conflict.key];
-      }
-    }
-  }
-  return resolved;
-}
-function getActionForMode(mode, conflict, customActions) {
-  switch (mode) {
-    case "keep_all":
-      return "keep";
-    case "auto_resolve":
-      return "reset";
-    case "remove_only":
-      return conflict.reason === "unsupported_key" ? "reset" : "keep";
-    case "custom":
-      return customActions[conflict.key] ?? "keep";
-  }
-}
-function computeOverrideDiff(defaults, proposed) {
-  const diff = {};
-  const defaultsRecord = defaults;
-  const proposedRecord = proposed;
-  for (const [key, proposedValue] of Object.entries(proposedRecord)) {
-    if (proposedValue === void 0 || proposedValue === null) continue;
-    const defaultValue = defaultsRecord[key];
-    if (JSON.stringify(proposedValue) !== JSON.stringify(defaultValue)) {
-      diff[key] = proposedValue;
-    }
-  }
-  for (const [key, defaultValue] of Object.entries(defaultsRecord)) {
-    if (defaultValue === void 0 || defaultValue === null) continue;
-    const proposedValue = proposedRecord[key];
-    if (proposedValue === void 0 || proposedValue === null) {
-      diff[key] = null;
-    }
-  }
-  return diff;
-}
-function effectiveOfferingPinOf(entry) {
-  if (!entry) return void 0;
-  const overrides = entry.overrides ?? {};
-  const raw = "offering_id" in overrides ? overrides.offering_id : entry.defaults?.offering_id;
-  return typeof raw === "string" && raw !== "" ? raw : void 0;
-}
-const UI_ONLY_SET = new Set(UI_GATE_KEYS);
-function buildApiPayload(effectiveSettings, overrides, context) {
-  const source = context === "chat" ? overrides : effectiveSettings;
-  const payload = {};
-  for (const [key, value] of Object.entries(source)) {
-    if (UI_ONLY_SET.has(key)) continue;
-    if (value === void 0 || value === null) continue;
-    payload[key] = value;
-  }
-  for (const [key, value] of Object.entries(overrides)) {
-    if (UI_ONLY_SET.has(key)) continue;
-    if (value === null) payload[key] = null;
-  }
-  return payload;
-}
-function mergeEffectiveSettings(defaults, overrides) {
-  const merged = { ...defaults };
-  for (const [key, value] of Object.entries(overrides)) {
-    if (value === null) delete merged[key];
-    else if (value !== void 0) merged[key] = value;
-  }
-  return merged;
-}
-function mergeVariableValues(variableDefaults, variableOverrides) {
-  const result = {};
-  for (const variable of variableDefaults) {
-    result[variable.name] = String(variable.defaultValue ?? "");
-  }
-  for (const [name, value] of Object.entries(variableOverrides)) {
-    result[name] = value;
-  }
-  return result;
-}
-function sanitizeSettings(raw) {
-  if (!raw || typeof raw !== "object") return {};
-  const clean = {};
-  for (const [key, value] of Object.entries(raw)) {
-    if (value !== null && value !== void 0) {
-      clean[key] = value;
-    }
-  }
-  return clean;
-}
-export {
-  PARAM_ALIASES,
-  buildApiPayload,
-  computeOverrideDiff,
-  detectConflicts,
-  effectiveOfferingPinOf,
-  extractModelDefaults,
-  getActionForMode,
-  mergeEffectiveSettings,
-  mergeVariableValues,
-  parseModelControls,
-  resolveConflicts,
-  sanitizeSettings
-};
+export * from "@ai-matrx/agents/settings";

package/dist/agents/redux/agent-settings/settings-catalogue.d.ts

@@ -1,78 +1,2 @@
-/**
- * Model Settings Catalogue — the single source of truth for the STANDARD
- * settings list, and the one chokepoint that decides which keys it contains.
- *
- * ── The model (two distinct surfaces) ────────────────────────────────────────
- *   1. STANDARD list  — ONLY the keys the selected model explicitly declares in
- *      its `controls` config (i.e. the parameters this model actually supports).
- *      `buildSettingsRows()` returns exactly these, grouped + ordered. Catalogue
- *      keys the model does not declare are NOT shown here.
- *   2. CAUTION surface — settings the agent has SET that the model does NOT
- *      support. These are never hidden: they are flagged as "not valid for this
- *      model" and made repairable by the validation layer (the IssueTable, fed
- *      by the `unsupported_by_model` rule). They do NOT belong in the standard
- *      list — that is exactly the "showing all possible keys" bug.
- *
- * The catalogue exists so the standard list's labels, grouping and order live
- * in ONE place (previously copy-pasted as `textModelSettings` /
- * `booleanSettings` / ... into three components, each filtering by
- * `getControl(key)` inline — which drifted and regressed). Components map over
- * `buildSettingsRows()`; they must not filter by model themselves (ESLint
- * enforces). The original recurring bug — set values silently dropped when a
- * model didn't support them — is fixed by the CAUTION surface, not by dumping
- * every key into the standard list.
- *
- * Guardrail: `settings-catalogue.test.ts` asserts the standard list contains
- * ONLY supported keys (never the full catalogue), and `unsupported-by-model.
- * test.ts` asserts set-but-unsupported keys surface in the caution layer.
- */
-import type { ControlDefinition } from "./types.js";
-export type SettingsGroupId = "text" | "featureFlags" | "imageVideo" | "audio" | "other";
-export interface CatalogueEntry {
-    key: string;
-    label: string;
-}
-export interface CatalogueGroup {
-    id: SettingsGroupId;
-    /** Section header shown above the group. Empty string = no header (lead group). */
-    label: string;
-    entries: CatalogueEntry[];
-}
-export declare const SETTINGS_CATALOGUE: CatalogueGroup[];
-/** Flat set of every key the catalogue declares. */
-export declare const CATALOGUE_KEYS: ReadonlySet<string>;
-export interface SettingsRow {
-    key: string;
-    label: string;
-    group: SettingsGroupId;
-    /** The model's control definition for this key. Standard rows are always
-     *  supported, so this is present; typed nullable for consumer convenience. */
-    control: ControlDefinition | null;
-    /** Always true for rows returned by buildSettingsRows (standard = supported). */
-    supported: boolean;
-    /** True when the current settings hold a non-null value for this key. */
-    hasValue: boolean;
-}
-export interface RenderGroup {
-    id: SettingsGroupId;
-    label: string;
-    rows: SettingsRow[];
-}
-/** A minimal structural view of a model's normalized controls. Accepts either
- *  NormalizedControls variant in the codebase (both are a key→ControlDefinition
- *  map plus rawControls/unmappedControls). */
-type ControlsLike = Record<string, unknown> | null | undefined;
-/**
- * Build the STANDARD settings list for the selected model.
- *
- * CONTRACT: returns ONLY keys the model declares a control for (supported).
- * Catalogue keys the model does not declare are omitted — they are not "shown"
- * in the standard list. Set-but-unsupported keys are NOT returned here either;
- * the caution layer (validation IssueTable) surfaces and repairs those.
- *
- * The catch-all "Other" group carries supported keys the model declares that
- * the catalogue doesn't name yet — so a brand-new model control still appears
- * without a code change. Empty groups are returned (consumers skip them).
- */
-export declare function buildSettingsRows(controls: ControlsLike, settings: Record<string, unknown> | null | undefined): RenderGroup[];
-export {};
+/** Agent settings live in the agent core (B4): `@ai-matrx/agents/settings`. */
+export * from "@ai-matrx/agents/settings";