Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix(embedded): openEngine refuses unknown settings keys, naming the key (B3a C)
garrytan484f082cc36f
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex 25f3b1b596..084d692dc2 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1420,6 +1420,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;// GBRA-200 (harness ask 6: stamp degraded replies). `since` is stamped at the merge slot.{ since: '0.60.563.0', id: 'write_grant_refusal_gbra200', text: 'A `remember` naming a `source_id` outside the connection\'s write grant is still refused `scope_denied` (a page write: `permission_denied`), and the refusal now carries `writable_source_ids`: the sources the connection\'s own grant lets it write, never another source, identical whether the named source exists or not. On `remember` the `fix` repeats the call against that source once the user agrees (`next: ask_user`, naming both sources), so a harness can retry instead of giving up; `forget`, `forget_fact` and page writes carry no fix.' },{ since: '0.60.563.0', id: 'degraded_stamp_gbra200', text: 'Every degraded or partial read result now carries one stamp naming why with stable codes: an MCP result gets `_meta.degraded: { reasons: [...] }` and one extra text block, `[gbrain degraded: <reasons>] ...`, after the others; a CLI `--json` object gets a `degraded` key, and other CLI output (human text, a bare `--json` array such as search results) gets that line on stderr. It covers search, query, recall, find_experts, context_pack, delta, entity, get_page (`file_held`), think and synthesize, search_exact, open_loops and rank_entities. recall and think no longer drop their page search\'s degraded stages (an embed timeout, a failed arm, the keyword rank bound): recall reports them in `_meta.retrieval.degraded` and its `degraded_recall` notice, think and synthesize as `GATHER_DEGRADED:<stage>` warnings, and a keyword-only search or recall on Postgres reports `keyword_candidates_incomplete` when the rank bound applies. A clean result carries no stamp, and no existing field changed.' },+ { since: 'TBD', id: 'embedded_scope_required_gbra283', text: 'Experimental embedded engines (`openEngine` with `embedded_core: true`) only; the CLI, `gbrain serve` and mounts are unchanged. While such an engine is open, an embed, chat, expansion or rerank call that entered no scope now refuses `engine_scope_required` (new code) even when the host configured a process gateway with `configureGateway`; before, that configuration let unscoped calls use the process keys, and the refusal was `engine_scope_missing`, which now only means a provider the engine lacks or a closed engine. Wrap such calls in `withEngineScope(engine, fn)`, or `withLocalScope(fn)` for calls that belong to the process gateway (both from `gbrain/engine-open`); `hybridSearch`, the import paths, minion jobs and `POST /mcp` enter their engine\'s scope themselves. `openEngine` also refuses an unknown settings key, top-level or nested, with `engine_settings_invalid` naming the key, where it used to ignore it. An embedded engine\'s chat usage is no longer on the process usage stack and survives `reconnect()`. See docs/ENGINES.md "Upgrading an embedded host".' },];/** The newest disclosed change's release: the notice id moves only when a release adds rows. */diff --git a/src/core/engine-open.ts b/src/core/engine-open.tsindex 01474f11a3..deac930dfd 100644--- a/src/core/engine-open.ts+++ b/src/core/engine-open.ts@@ -56,7 +56,24 @@ function checkAI(ai: EngineAISettings): void {}}+/** Each setting openEngine reads, with the fields it reads inside it (null: a value, or fields another check reads: ai.providers, storage in Wave C). */+const SETTINGS_FIELDS: Record<string, readonly string[] | null> = {+ embedded_core: null, engine: null, database: ['url', 'directUrl', 'path'], pool: ['max'], host: ['id'], writer: ['id', 'credential', 'lane'],+ embedding: ['model', 'dimensions'], keyword_statement_timeout_ms: null, pglite: ['shared_buffers'], ai: ['providers', 'models'], storage: null,+};++/** A misspelled or foreign key would be silently ignored, so it refuses, naming the key and never its value. */+function checkKnownKeys(settings: EngineSettings): void {+ for (const [name, value] of Object.entries(settings)) {+ if (!Object.hasOwn(SETTINGS_FIELDS, name)) throw invalid(name, `openEngine reads ${Object.keys(SETTINGS_FIELDS).join(', ')}, so a misspelled or foreign setting would be ignored.`);+ const fields = SETTINGS_FIELDS[name];+ const extra = fields && value && typeof value === 'object' ? Object.keys(value).find(field => !fields.includes(field)) : undefined;+ if (extra) throw invalid(`${name}.${extra}`, `${name} takes ${fields!.join(', ')}.`);+ }+}+function checkSettings(settings: EngineSettings): void {+ checkKnownKeys(settings);if (settings.engine !== 'postgres' && settings.engine !== 'pglite') throw invalid('engine', "engine is 'postgres' or 'pglite'.");const database = settings.database;if (!database || typeof database !== 'object') throw invalid('database', 'database is an object: { url, directUrl? } for Postgres, { path? } for PGLite.');diff --git a/test/engine-open-settings-keys.test.ts b/test/engine-open-settings-keys.test.tsnew file mode 100644index 0000000000..36c36cdeca--- /dev/null+++ b/test/engine-open-settings-keys.test.ts@@ -0,0 +1,46 @@+/**+ * GBRA-283 B3a (N1): openEngine refuses a settings key it does not know, at the top level or inside a known setting,+ * with engine_settings_invalid naming the key, so a misspelled setting is never silently ignored. `storage` is known+ * (Wave C checks its fields).+ */+import { describe, expect, test } from 'bun:test';+import { randomUUID } from 'node:crypto';+import { openEngine, type EngineSettings } from '../src/core/engine-open.ts';++const base = (): Record<string, unknown> => ({ embedded_core: true, engine: 'pglite', database: {}, host: { id: randomUUID() } });+const refusal = async (settings: Record<string, unknown>) => {+ try { await (await openEngine(settings as unknown as EngineSettings)).disconnect(); return null; } catch (error) { return error as Error & { code?: string; suggestion?: string }; }+};++describe('unknown settings keys', () => {+ const cases: Array<[string, Record<string, unknown>, string]> = [+ ['a misspelled top-level setting', { embeding: { model: 'openai:text-embedding-3-small', dimensions: 1536 } }, 'embeding'],+ ['a top-level setting from another product', { region: 'us-west-2' }, 'region'],+ ['database', { database: { path: undefined, pathh: '/tmp/x' } }, 'database.pathh'],+ ['pool', { pool: { max: 2, min: 1 } }, 'pool.min'],+ ['host', { host: { id: randomUUID(), name: 'brain-a' } }, 'host.name'],+ ['writer', { writer: { id: randomUUID(), credential: 'c'.repeat(64), lane: 'cli', scope: 'all' } }, 'writer.scope'],+ ['embedding', { embedding: { model: 'openai:text-embedding-3-small', dimensions: 1536, dims: 1536 } }, 'embedding.dims'],+ ['pglite', { pglite: { sharedBuffers: '64MB' } }, 'pglite.sharedBuffers'],+ ['ai', { ai: { providers: {}, model: { chat: 'openai:gpt-5.6' } } }, 'ai.model'],+ ];+ for (const [label, extra, named] of cases) {+ test(`${label}: refuses engine_settings_invalid naming ${named}`, async () => {+ const error = await refusal({ ...base(), ...extra });+ expect(error?.code).toBe('engine_settings_invalid');+ expect(error?.message).toContain(`The ${named} setting is invalid.`);+ });+ }++ test('the value of an unknown key is never echoed', async () => {+ const secret = `sk-secret-${randomUUID()}`;+ const error = await refusal({ ...base(), openai_api_key: secret });+ expect(error?.code).toBe('engine_settings_invalid');+ expect(`${error?.message} ${error?.suggestion}`).not.toContain(secret);+ });++ test('every known key opens, storage included (Wave C checks its fields)', async () => {+ const settings = { ...base(), pool: { max: 2 }, embedding: { model: 'openai:text-embedding-3-small', dimensions: 1536 }, keyword_statement_timeout_ms: 1000, pglite: {}, storage: {} };+ expect(await refusal(settings)).toBeNull();+ }, 60_000);+});