Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 101 additions & 16 deletions apps/memos-local-plugin/core/config/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@

import { promises as fs } from "node:fs";

import { Type } from "@sinclair/typebox";
import { KindGuard, Type } from "@sinclair/typebox";
import { Value, type ValueError } from "@sinclair/typebox/value";

import { MemosError } from "../../agent-contract/errors.js";
Expand Down Expand Up @@ -87,7 +87,7 @@ export async function loadConfig(home: ResolvedHome, agent?: string): Promise<Lo
* freshly built copy, so callers may pass shared or cached objects safely.
*/
export function resolveConfig(raw: unknown, warnings?: string[], agent?: string): ResolvedConfig {
const cleaned = pruneUnknown(raw, DEFAULT_CONFIG, "", warnings);
const cleaned = pruneUnknown(raw, ConfigSchema, "", warnings);
// Resolve masked/placeholder secret values from the environment before
// merging. `maskSecrets()` (pipeline/memory-core.ts) rewrites every
// SECRET_FIELD_PATHS leaf to `__memos_secret__` before the config is
Expand Down Expand Up @@ -308,41 +308,126 @@ function deepMerge<T extends Record<string, unknown>>(a: T, b: Record<string, un
}

/**
* Walk `raw` against `defaults` shape; record warnings for any keys that
* have no counterpart (likely from a removed schema). We pass them through
* anyway so older configs keep working.
* Walk `raw` against the TypeBox schema shape at this level; record warnings
* for any keys with no counterpart in the schema (likely a typo, or a key
* that was renamed/removed). Unknown values are passed through unchanged so
* old configs keep loading.
*
* Why the schema (and not `DEFAULT_CONFIG`) is the source of truth here:
* `DEFAULT_CONFIG` only lists fields with a concrete default value. Any
* `Type.Optional(...)` field that intentionally has no default (for
* example `llm.reasoning` → `ReasoningSchema` — omitting the whole block
* is semantically different from "an empty one") would be flagged as
* unknown on every boot even though the schema declares it. #2247 /
* #2248 (`llm.maxTokens`, `llm.headers`) papered over this by adding
* concrete defaults; this walker fixes the whole class of future
* optional fields in one place.
*
* `FREE_FORM_CONFIG_PATHS` is still honoured as an explicit allowlist
* for backward compatibility and for the (currently non-existent) case
* where an operator wants a plain `Type.Object` branch to accept
* arbitrary child keys without declaring them as `patternProperties`.
* TypeBox `Type.Record` schemas already advertise themselves via
* `patternProperties` and are detected automatically.
*/
function pruneUnknown(
raw: unknown,
defaults: unknown,
schemaNode: unknown,
prefix: string,
warnings?: string[],
): Record<string, unknown> {
if (!isPlainObject(raw)) return {};
const known = schemaObjectProperties(schemaNode);
const freeFormHere = schemaAcceptsAnyKey(schemaNode);
const out: Record<string, unknown> = {};
// Fallback: the schema node at this level is neither a plain `Type.Object`
// (so `known` is null) nor a free-form map (so `freeFormHere` is false).
// We cannot validate child keys here. Pass them through verbatim and emit
// a single diagnostic so the bypass is visible — otherwise a future schema
// refactor that puts a `Type.Union`, `Type.Intersect`, or `Type.Any` at a
// node `pruneUnknown` recurses into would silently disable validation for
// the whole subtree. TypeBox's `Value.Errors` still catches structural
// problems at the end of `resolveConfig`; this warning just makes the
// bypass easy to discover during debugging. The current schema is entirely
// composed of `Type.Object` and `Type.Record` so this branch is dormant
// today, but it stops being a latent trap tomorrow.
if (known === null && !freeFormHere) {
warnings?.push(
`config: cannot validate child keys of '${prefix || "<root>"}' ` +
`(schema node is neither Type.Object nor a free-form map) — ` +
`passing all keys through unchanged`,
);
for (const [k, v] of Object.entries(raw)) out[k] = v;
return out;
}
for (const [k, v] of Object.entries(raw)) {
const path = prefix ? `${prefix}.${k}` : k;
if (isPlainObject(defaults) && !(k in (defaults as Record<string, unknown>))) {
// Free-form maps keep every user-defined child key verbatim: TypeBox
// `Type.Record(...)` surfaces as `patternProperties` (detected via
// `freeFormHere`), and the explicit allowlist handles any legacy
// sections we want to treat the same way.
if (freeFormHere || FREE_FORM_CONFIG_PATHS.includes(path)) {
out[k] = v;
continue;
}
// `known` is guaranteed non-null here: the only way `freeFormHere` is
// false while `known` is null was handled by the early-return above.
// TypeScript can't follow that cross-loop narrowing, so pin it locally.
const knownKeys = known as Record<string, unknown>;
if (!(k in knownKeys)) {
warnings?.push(`unknown config key '${path}' (kept as-is for forward compatibility)`);
out[k] = v;
continue;
}
if (isPlainObject(v) && isPlainObject((defaults as Record<string, unknown>)[k])) {
if (FREE_FORM_CONFIG_PATHS.includes(path)) {
// Explicitly declared free-form maps keep user-defined child keys.
// Other empty default objects remain structured config sections and
// continue to report unknown nested keys.
out[k] = v;
continue;
}
out[k] = pruneUnknown(v, (defaults as Record<string, unknown>)[k], path, warnings);
const childSchema = knownKeys[k];
if (isPlainObject(v) && isObjectSchema(childSchema)) {
out[k] = pruneUnknown(v, childSchema, path, warnings);
} else {
out[k] = v;
}
}
return out;
}

/**
* TypeBox `Type.Object(...)` → the `properties` map; null for anything else
* (`Type.Record`, `Type.Union`, scalar schemas, non-schema values, …). We go
* through `KindGuard.IsObject` rather than hand-rolling a `type === "object"`
* check so the introspection stays aligned with TypeBox's own notion of what
* is a `TObject` — if TypeBox ever changes its internal representation we
* only have to update the import, not three helpers.
*/
function schemaObjectProperties(node: unknown): Record<string, unknown> | null {
if (!KindGuard.IsObject(node)) return null;
const props = (node as { properties?: unknown }).properties;
return isPlainObject(props) ? (props as Record<string, unknown>) : null;
}

/**
* TypeBox `Type.Record(...)` surfaces as a schema with `patternProperties`;
* `KindGuard.IsRecord` detects it directly. We also treat
* `additionalProperties: true` the same way — nothing in the current schema
* uses it, but it keeps us aligned with JSON Schema semantics for future
* flexibility.
*/
function schemaAcceptsAnyKey(node: unknown): boolean {
if (KindGuard.IsRecord(node)) return true;
if (!isPlainObject(node)) return false;
const additional = (node as { additionalProperties?: unknown }).additionalProperties;
return additional === true;
}

/**
* A schema node that `pruneUnknown` should recurse into — either a
* `Type.Object` (child validation drives the known-key check) or a
* `Type.Record` (free-form map handled by `schemaAcceptsAnyKey`). Other
* schema shapes (unions, intersections, scalars) are left to TypeBox's
* `Value.Errors` to validate.
*/
function isObjectSchema(node: unknown): boolean {
return KindGuard.IsObject(node) || KindGuard.IsRecord(node);
}

function isPlainObject(v: unknown): v is Record<string, unknown> {
return typeof v === "object" && v !== null && !Array.isArray(v);
}
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
/**
* Regression tests for issue #2474.
*
* The `pruneUnknown` validator used to key its "known fields" set on
* `DEFAULT_CONFIG`, so any TypeBox `Type.Optional(...)` field without a
* default (e.g. `llm.reasoning` → `ReasoningSchema`) was reported as an
* unknown key on every boot:
*
* config.warning message="unknown config key 'llm.reasoning' (kept as-is …)"
* config.warning message="unknown config key 'skillEvolver.reasoning' (…)"
* config.warning message="unknown config key 'l3Llm.reasoning' (…)"
*
* Fix: derive the known-key set from the TypeBox schema (`ConfigSchema`),
* not from the defaults tree. This covers every current and future
* optional field in one place.
*
* Precedent: #2248 added `llm.maxTokens` / `llm.headers` to `DEFAULT_CONFIG`
* to cure the same class of warning. The schema-driven rewrite subsumes
* that approach.
*/

import { describe, expect, it } from "vitest";

import { resolveConfig } from "../../../core/config/index.js";

const UNKNOWN_WARN_RE = /unknown config key/;

describe("resolveConfig schema-driven unknown-key detection (issue #2474)", () => {
it("does not warn for llm.reasoning (an optional field declared in the schema)", () => {
const warnings: string[] = [];
const cfg = resolveConfig({ llm: { reasoning: { enabled: false } } }, warnings);
expect(warnings.filter((w) => UNKNOWN_WARN_RE.test(w))).toEqual([]);
expect(cfg.llm.reasoning).toEqual({ enabled: false });
});

it("does not warn for skillEvolver.reasoning", () => {
const warnings: string[] = [];
const cfg = resolveConfig(
{ skillEvolver: { reasoning: { effort: "medium" } } },
warnings,
);
expect(warnings.filter((w) => UNKNOWN_WARN_RE.test(w))).toEqual([]);
expect(cfg.skillEvolver.reasoning).toEqual({ effort: "medium" });
});

it("does not warn for l3Llm.reasoning", () => {
const warnings: string[] = [];
const cfg = resolveConfig(
{ l3Llm: { reasoning: { maxTokens: 2048 } } },
warnings,
);
expect(warnings.filter((w) => UNKNOWN_WARN_RE.test(w))).toEqual([]);
expect(cfg.l3Llm.reasoning).toEqual({ maxTokens: 2048 });
});

it("still warns on real typos inside a known schema branch", () => {
const warnings: string[] = [];
resolveConfig({ llm: { reasonning: {} } }, warnings);
expect(warnings).toContain(
"unknown config key 'llm.reasonning' (kept as-is for forward compatibility)",
);
});

it("still warns on top-level unknown branches", () => {
const warnings: string[] = [];
resolveConfig({ entityExtractor: { reasoning: { enabled: true } } }, warnings);
expect(
warnings.some((w) =>
/unknown config key 'entityExtractor'/.test(w),
),
).toBe(true);
});

it("keeps nested free-form map child keys without warning (llm.headers via schema Record)", () => {
const warnings: string[] = [];
const cfg = resolveConfig(
{ llm: { headers: { "X-A": "1", "X-B": "2" } } },
warnings,
);
expect(warnings.filter((w) => UNKNOWN_WARN_RE.test(w))).toEqual([]);
expect(cfg.llm.headers).toEqual({ "X-A": "1", "X-B": "2" });
});

it("keeps logging.channels user-defined child keys without warning (Record)", () => {
const warnings: string[] = [];
const cfg = resolveConfig(
{ logging: { channels: { "core.l2.cross-task": "debug" } } },
warnings,
);
expect(warnings.filter((w) => UNKNOWN_WARN_RE.test(w))).toEqual([]);
expect(cfg.logging.channels).toEqual({ "core.l2.cross-task": "debug" });
});

it("resolved config retains the reasoning block exactly as specified", () => {
const cfg = resolveConfig({
llm: {
reasoning: { enabled: true, effort: "high", maxTokens: 4096 },
},
skillEvolver: {
reasoning: { enabled: false },
},
l3Llm: {
reasoning: { effort: "low" },
},
});
expect(cfg.llm.reasoning).toEqual({ enabled: true, effort: "high", maxTokens: 4096 });
expect(cfg.skillEvolver.reasoning).toEqual({ enabled: false });
expect(cfg.l3Llm.reasoning).toEqual({ effort: "low" });
});

it("still warns on unknown nested keys inside the reasoning block itself", () => {
const warnings: string[] = [];
resolveConfig(
{ llm: { reasoning: { unknownKnob: 1 } } },
warnings,
);
expect(warnings).toContain(
"unknown config key 'llm.reasoning.unknownKnob' (kept as-is for forward compatibility)",
);
});
});
Loading