Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix: engine scopes hold before the first embedded open, entry points leave a foreign scope, unscoped reads stay strict
garrytanb12f5a66d721
diff --git a/src/core/embedded-engine.ts b/src/core/embedded-engine.tsindex e6a12b4dd0..28faa498f5 100644--- a/src/core/embedded-engine.ts+++ b/src/core/embedded-engine.ts@@ -108,7 +108,7 @@ export function settingsConnectionOptions(url: string): { host: string; port: nuconst records = new WeakMap<object, EmbeddedRecord>();let embeddedProcess = false;let openEmbeddedEngines = 0;-setEmbeddedKeyResolver(engine => (records.has(engineKey(engine)) ? engineKey(engine) : undefined));+setEmbeddedKeyResolver(engine => (records.has(engineKey(engine)) ? engineKey(engine) : undefined), processHoldsEmbeddedEngines);function recordOf(engine: object): EmbeddedRecord | undefined {return records.get(engineKey(engine));diff --git a/src/core/engine-scope-store.ts b/src/core/engine-scope-store.tsindex a80c830d35..beaa87464a 100644--- a/src/core/engine-scope-store.ts+++ b/src/core/engine-scope-store.ts@@ -11,9 +11,17 @@ const LOCAL = Object.freeze({});/** Set by embedded-engine.ts when it loads (so before any engine is opened from settings): its engineKey, else undefined. */let embeddedKeyOf: (engine: object) => object | undefined = () => undefined;+/** Set with it: whether an embedded engine is open in this process. */+let holdsEmbedded: () => boolean = () => false;-export function setEmbeddedKeyResolver(resolve: (engine: object) => object | undefined): void {+export function setEmbeddedKeyResolver(resolve: (engine: object) => object | undefined, holds: () => boolean): void {embeddedKeyOf = resolve;+ holdsEmbedded = holds;+}++/** True for a call that entered no scope while an embedded engine is open: its brain is unknown, so a reader takes the strict policy. */+export function unscopedWithOpenEmbeddedEngines(): boolean {+ return engineScopeStore.getStore() === undefined && holdsEmbedded();}/** The engineKey of `engine` when it was opened from settings, else undefined. */diff --git a/src/core/engine-scope.ts b/src/core/engine-scope.tsindex d211e3dd45..ff584ab583 100644--- a/src/core/engine-scope.ts+++ b/src/core/engine-scope.ts@@ -8,21 +8,23 @@* A call decides by scope presence alone. In an embedded engine's scope it uses that engine's state; in a local scope* (withLocalScope, which the CLI, gbrain serve and the jobs worker enter, or any other engine's scope) the process* gateway; with no scope while the process holds an open embedded engine it refuses `engine_scope_required`. In a- * process that never opened an embedded engine nothing changes, and withEngineScope enters no scope at all.+ * process that never opened an embedded engine nothing changes.*/import { isEmbeddedEngine, processHasEmbeddedEngines, processHoldsEmbeddedEngines } from './embedded-engine.ts';+import { engineKey } from './engine-key.ts';import { engineScopeStore as scope } from './engine-scope-store.ts';export { withLocalScope } from './engine-scope-store.ts';-/** Runs `fn` as a call for `engine`. A plain call in a process that holds no embedded engine. */+/** Runs `fn` as a call for `engine`, also before the process opens its first embedded engine, so the call keeps its scope after one opens. */export function withEngineScope<T>(engine: object, fn: () => T): T {- return processHasEmbeddedEngines() ? scope.run(engine, fn) : fn();+ return scope.run(engine, fn);}-/** True when `engine` was opened from settings and the call does not run in its scope yet: the entry point re-enters itself in it. */+/** True in a process that opened an embedded engine when the call does not run in `engine`'s scope yet: the entry point re-enters itself in it. */export function needsEngineScope(engine: object): boolean {- return isEmbeddedEngine(engine) && scope.getStore() !== engine;+ const current = scope.getStore();+ return processHasEmbeddedEngines() && (current === undefined || engineKey(current) !== engineKey(engine));}/** The engine scope the current call runs in, for deferred work to resume in with runInEngineScope. */diff --git a/src/core/search/private-visibility.ts b/src/core/search/private-visibility.tsindex 0e8228e6ee..25c23bdb98 100644--- a/src/core/search/private-visibility.ts+++ b/src/core/search/private-visibility.ts@@ -22,7 +22,7 @@import { AsyncLocalStorage } from 'node:async_hooks';import type { BrainEngine } from '../engine.ts';-import { embeddedKey, embeddedKeyInScope } from '../engine-scope-store.ts';+import { embeddedKey, embeddedKeyInScope, unscopedWithOpenEmbeddedEngines } from '../engine-scope-store.ts';import { requestConfigRows } from '../config-snapshot.ts';import { isValidSourceId } from '../source-id.ts';import { ACCESS_ID_RE, hasReaders, MEMBER_PAGE_PREFIX, normalizePrincipal, readersAllow, validIdentity } from '../access/principals.ts';@@ -510,6 +510,7 @@ const ALIAS_OPT_OUT_VALUES = ['false', '0', 'off', 'no'];function honorAliases(): boolean {const scoped = embeddedKeyInScope();if (scoped) return embeddedPolicy.get(scoped)?.honorAliases ?? true;+ if (unscopedWithOpenEmbeddedEngines()) return true;return honorAliasEngines.size > 0 || aliasOptOutEngines.size === 0;}@@ -758,6 +759,7 @@ function processPrivacyRelaxed(): boolean {if (process.env.GBRAIN_REMOTE_PRIVATE_PAGES === '1') return true;const scoped = embeddedKeyInScope();if (scoped) return embeddedPolicy.get(scoped)?.expose === true;+ if (unscopedWithOpenEmbeddedEngines()) return false;return exposeEngines.size > 0 && strictEngines.size === 0;}diff --git a/src/core/search/rerank.ts b/src/core/search/rerank.tsindex 0d0ad69957..b97963df0b 100644--- a/src/core/search/rerank.ts+++ b/src/core/search/rerank.ts@@ -68,8 +68,10 @@ function hashQuery(query: string): string {function classifyRerankFailure(err: unknown): RerankFailureReason {if (err instanceof RerankError) return err.reason;- // An embedded engine given no provider for this reranker (engine-gateway.ts): nothing was sent, so a skip.- if ((err as { code?: unknown } | null)?.code === 'engine_scope_missing') return 'no_key';+ // An embedded engine given no provider for this reranker, or a call that entered no scope while one is open+ // (engine-gateway.ts): nothing was sent, so a skip.+ const code = (err as { code?: unknown } | null)?.code;+ if (code === 'engine_scope_missing' || code === 'engine_scope_required') return 'no_key';if (err instanceof BudgetExhausted ||(err && typeof err === 'object' && (err as { tag?: unknown }).tag === 'BUDGET_EXHAUSTED')diff --git a/test/engine-alias-policy.test.ts b/test/engine-alias-policy.test.tsindex d0c89bedd1..06e23de260 100644--- a/test/engine-alias-policy.test.ts+++ b/test/engine-alias-policy.test.ts@@ -10,8 +10,9 @@ import { openEngine, withEngineScope, withLocalScope, type EngineSettings } fromimport { createEngine } from '../src/core/engine-factory.ts';import {HONOR_ALIASES_KEY, REMOTE_PRIVATE_PAGES_KEY, __aliasPolicyEngineCountForTests, __resetPrivateVisibilityCacheForTests,- isPrivacyPrivatePage, readHonorAliases, remotePrivacyRelaxed,+ currentCallerAccess, isPrivacyPrivatePage, readHonorAliases, remotePrivacyRelaxed,} from '../src/core/search/private-visibility.ts';+import { waitFor } from './helpers/wait-for.ts';const settings = (): EngineSettings => ({ embedded_core: true, engine: 'pglite', database: {}, host: { id: randomUUID() } });const aliased = { type: 'note', frontmatter: { access: 'private' } };@@ -55,6 +56,25 @@ describe('per-engine alias and privacy policy', () => {}}, 120_000);+ test('an unscoped read stays strict while the process holds an embedded engine, whatever a local engine set', async () => {+ const embedded = await openEngine(settings());+ const local = await createEngine({ engine: 'pglite' });+ try {+ await local.connect({ engine: 'pglite' } as never);+ await local.initSchema();+ await local.setConfig(HONOR_ALIASES_KEY, 'false');+ await local.setConfig(REMOTE_PRIVATE_PAGES_KEY, 'visible');+ await readHonorAliases(local);+ await remotePrivacyRelaxed(local);+ expect(withLocalScope(() => isPrivacyPrivatePage(aliased))).toBe(false);+ expect(withLocalScope(() => currentCallerAccess().hidePrivate)).toBe(false);+ expect(isPrivacyPrivatePage(aliased)).toBe(true);+ expect(currentCallerAccess().hidePrivate).toBe(true);+ } finally {+ await Promise.all([embedded.disconnect(), local.disconnect()]);+ }+ }, 120_000);+test('open, read and close cycles retain no embedded engine in the policy sets', async () => {const refs: WeakRef<object>[] = [];for (let i = 0; i < 5; i++) {@@ -67,9 +87,7 @@ describe('per-engine alias and privacy policy', () => {await engine.disconnect();}expect(__aliasPolicyEngineCountForTests()).toBe(0);- Bun.gc(true);- await Bun.sleep(50);- Bun.gc(true);+ await waitFor(() => { Bun.gc(true); return refs.some(ref => ref.deref() === undefined); }, { timeoutMs: 10_000, intervalMs: 50, label: 'a closed engine collected' });expect(refs.filter(ref => ref.deref() !== undefined).length).toBeLessThan(refs.length);}, 120_000);});diff --git a/test/engine-scope-entry-points.test.ts b/test/engine-scope-entry-points.test.tsindex a4d3caa2d0..adea875fb9 100644--- a/test/engine-scope-entry-points.test.ts+++ b/test/engine-scope-entry-points.test.ts@@ -14,6 +14,7 @@ import { hybridSearch, hybridSearchCached } from '../src/core/search/hybrid.ts';import { MinionQueue } from '../src/core/minions/queue.ts';import { MinionWorker } from '../src/core/minions/worker.ts';import { waitFor } from './helpers/wait-for.ts';+import { createEngine } from '../src/core/engine-factory.ts';const EMBEDDING = { model: 'openai:text-embedding-3-small', dimensions: 1536 };const key = (label: string) => `sk-${label}-${randomBytes(12).toString('hex')}`;@@ -79,6 +80,25 @@ describe('entry points a host calls without a scope', () => {}}, 120_000);+ test('inside an embedded engine\'s scope, search on a local engine leaves that scope and uses the process gateway', async () => {+ installEmbedStub();+ const keyA = key('a');+ const a = await openEngine(settingsFor(keyA));+ const local = await createEngine({ engine: 'pglite' });+ try {+ await local.connect({ engine: 'pglite' } as never);+ await local.initSchema();+ await withEngineScope(a, async () => {+ await hybridSearch(local, 'acme-example note');+ await hybridSearchCached(local, 'acme-example plan');+ });+ expect(sent.length).toBeGreaterThan(0);+ expect(new Set(sent)).toEqual(new Set([`Bearer ${PROCESS_KEY}`]));+ } finally {+ await Promise.all([a.disconnect(), local.disconnect()]);+ }+ }, 120_000);+test('the minion worker runs each job in its engine\'s scope, whatever scope started it', async () => {installEmbedStub();const keyA = key('a');diff --git a/test/engine-scope-required.test.ts b/test/engine-scope-required.test.tsindex a427e5db0f..8c4deed37d 100644--- a/test/engine-scope-required.test.ts+++ b/test/engine-scope-required.test.ts@@ -18,6 +18,9 @@ import { openEngine, withEngineScope, withLocalScope, type EngineSettings } fromimport { createEngine } from '../src/core/engine-factory.ts';import type { BrainEngine } from '../src/core/engine.ts';import { withEnv } from './helpers/with-env.ts';+import { spawnSync } from 'node:child_process';+import { applyReranker } from '../src/core/search/rerank.ts';+import type { SearchResult } from '../src/core/types.ts';const EMBEDDING = { model: 'openai:text-embedding-3-small', dimensions: 1536 };const key = (label: string) => `sk-${label}-${randomBytes(12).toString('hex')}`;@@ -153,6 +156,52 @@ describe('a mixed process: a local CLI engine and two embedded engines', () => {}, 60_000);});+describe('rerank in a process holding an embedded engine', () => {+ test('an unscoped rerank skips as no_key: nothing was sent, so no provider failure is reported', async () => {+ installStubs();+ configureConflictingProcessGateway();+ const engine = await openEngine(settingsFor(key('a')));+ const seen: string[] = [];+ try {+ const results = [{ slug: 'notes/one', chunk_text: 'one', score: 1 }, { slug: 'notes/two', chunk_text: 'two', score: 0.5 }] as unknown as SearchResult[];+ const out = await applyReranker('rerank query', results, {+ enabled: true, topNIn: 2, topNOut: null, timeoutMs: 1000, model: 'voyage:rerank-3-lite',+ onSkip: reason => { seen.push(`skip:${reason}`); }, onFailure: reason => { seen.push(`failure:${reason}`); },+ });+ expect(out).toBe(results);+ expect(seen).toEqual(['skip:no_key']);+ expect(sent).toEqual([]);+ } finally {+ await engine.disconnect();+ }+ }, 60_000);+});++describe('a process that has not opened an embedded engine yet', () => {+ test('a call that entered a local engine scope before the first embedded engine opened keeps that scope after it opens', () => {+ const src = (path: string) => JSON.stringify(join(import.meta.dir, '..', 'src', path));+ const script = `+ const { __setGenerateTextTransportForTests, chat, configureGateway } = await import(${src('core/ai/gateway.ts')});+ const { openEngine, withEngineScope } = await import(${src('core/engine-open.ts')});+ __setGenerateTextTransportForTests(async () => ({ content: [{ type: 'text', text: 'ok' }], finishReason: 'stop', usage: { inputTokens: 1, outputTokens: 1 } }));+ configureGateway({ embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: 1536, chat_model: 'openai:gpt-5.6', env: { OPENAI_API_KEY: 'sk-process-local' } });+ let release; const gate = new Promise(resolve => { release = resolve; });+ const localEngine = { name: 'local-engine' };+ const local = withEngineScope(localEngine, async () => {+ await gate;+ try { await chat({ messages: [{ role: 'user', content: 'hello' }] }); return 'ok'; } catch (error) { return error?.code ?? String(error); }+ });+ const engine = await openEngine({ embedded_core: true, engine: 'pglite', database: {}, host: { id: crypto.randomUUID() } });+ release();+ const outcome = await local;+ await engine.disconnect();+ console.log('OUTCOME=' + outcome);+ `;+ const run = spawnSync(process.execPath, ['-e', script], { encoding: 'utf-8', timeout: 60_000 });+ expect(run.stdout).toContain('OUTCOME=ok');+ }, 90_000);+});+describe('a process with no open embedded engine', () => {test('an unscoped call uses the process gateway as before, and does again once every embedded engine closed', async () => {installStubs();