Skip to content

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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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);
+});