Skip to content

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.ts
index 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: nu
const 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 } from
import { 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.ts
index 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.ts
index 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 } from
import { 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();