Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(embedded): host entry points and the minion worker enter the engine's scope (B3a B)

garrytan509abcd2a73b
diff --git a/src/commands/serve-http-mcp.ts b/src/commands/serve-http-mcp.ts
index 8fbfb508c4..954188072f 100644
--- a/src/commands/serve-http-mcp.ts
+++ b/src/commands/serve-http-mcp.ts
@@ -30,6 +30,7 @@ import { scopeDeniedError } from '../core/ops/op-fix.ts';
import { resolveStrictParamsMode } from '../mcp/validate-params.ts';
import { GBRAIN_CLIENT_HEADER, isGbrainThinClient, resolveResultRowsMode, resultRowsForRequest, type ResultRowsMode } from '../mcp/result-rows.ts';
import { buildToolDefs } from '../mcp/tool-defs.ts';
+import { withEngineScope } from '../core/engine-scope.ts';
import {
filterOpsForSurface,
advertisedOps,
@@ -138,7 +139,7 @@ export function mountMcp(app: Express, ctx: ServeHttpContext): void {
// read-only; grantScopes still caps each grant to the client row's scope.
app.post('/mcp', withBearerScopeHint(
requireBearerAuth({ verifier: resourceVerifier, resourceMetadataUrl }), ['read', 'write'],
- ), (req: Request, res: Response) => withRequestConfigSnapshot(engine, () => handleMcpPost(req, res)));
+ ), (req: Request, res: Response) => withEngineScope(engine, () => withRequestConfigSnapshot(engine, () => handleMcpPost(req, res))));
// #6721: one config snapshot serves every config read of one POST /mcp (the
// surface, row-shape and writeback reads below, tools/list and a read op's
diff --git a/src/core/import-file.ts b/src/core/import-file.ts
index 479fe4e3da..7d87ff815f 100644
--- a/src/core/import-file.ts
+++ b/src/core/import-file.ts
@@ -70,6 +70,7 @@ import type { PageBodyPolicy } from './page-body/limits.ts';
import { parseFactsFence, renderFactsTable, restoreHiddenFactRows, factsGapWarning, replaceOrInsertFactsFence } from './facts-fence.ts';
import { assertOriginUnclaimed, isOriginClaimRefusal } from './persistence/origin-guard.ts';
import { fileBodyMatchesStored, readStoredBody } from './facts/file-body-guard.ts';
+import { needsEngineScope, withEngineScope } from './engine-scope.ts';
/**
* #2044 / #4548: row-level, visibility-aware fence merge for one page
@@ -352,6 +353,7 @@ export async function importFromContent(
onPostCommitEmbedding?: (complete: () => Promise<ImportEmbeddingResult>) => void;
} & ImportFenceOptions = {},
): Promise<ImportResult> {
+ if (needsEngineScope(engine)) return withEngineScope(engine, () => importFromContent(engine, slug, content, opts));
// Normalize BEFORE any tx write: putPage lowercases via validateSlug but
// upsertChunks used to query by the caller's raw slug, so a mixed-case slug
// created the page row then failed the chunk upsert with "Page not found",
@@ -1035,6 +1037,7 @@ export async function importFromFile(
bodyPolicy?: PageBodyPolicy;
} = {},
): Promise<ImportResult> {
+ if (needsEngineScope(engine)) return withEngineScope(engine, () => importFromFile(engine, filePath, relativePath, opts));
// Defense-in-depth: reject symlinks before reading content.
const lstat = lstatSync(filePath);
if (lstat.isSymbolicLink()) {
@@ -1235,6 +1238,7 @@ export async function importCodeFile(
opts: { noEmbed?: boolean; force?: boolean; sourceId?: string;
prepare?: (prepared: import('./persistence/prepared-import.ts').PreparedContentImport) => Promise<ImportResult> } = {},
): Promise<ImportResult> {
+ if (needsEngineScope(engine)) return withEngineScope(engine, () => importCodeFile(engine, relativePath, content, opts));
if (!opts.prepare) await assertUnmanagedCanonicalWriter(engine, 'direct file import', { sourceId: opts.sourceId ?? 'default' });
if (opts.prepare && !opts.noEmbed) throw new Error('Coordinated code import requires provider-free preparation.');
const slug = slugifyCodePath(relativePath);
@@ -1869,6 +1873,7 @@ export async function importImageFile(
relativePath: string,
opts: ImportImageOptions = {},
): Promise<ImportResult> {
+ if (needsEngineScope(engine)) return withEngineScope(engine, () => importImageFile(engine, filePath, relativePath, opts));
if (!opts.prepare) await assertUnmanagedCanonicalWriter(engine, 'direct file import', { sourceId: opts.sourceId ?? 'default' });
// Defense-in-depth: reject symlinks before reading bytes.
const lstat = lstatSync(filePath);
diff --git a/src/core/minions/worker.ts b/src/core/minions/worker.ts
index d013449aa4..a1d6d101d6 100644
--- a/src/core/minions/worker.ts
+++ b/src/core/minions/worker.ts
@@ -94,6 +94,7 @@ import { DEFAULT_LONG_JOB_NAMES, DEFAULT_SHORT_JOB_RESERVED_SLOTS, claimExclusio
import { jobRefusal, refusedJobResult } from './refusal.ts';
import { readFileSync } from 'fs';
import { parseRssFromProcStatus } from './proc-rss.ts';
+import { withEngineScope } from '../engine-scope.ts';
export { parseRssFromProcStatus };
@@ -1535,7 +1536,7 @@ export class MinionWorker extends EventEmitter {
})
// #4218: attribute every gateway.chat() the handler makes to this
// job so chat_usage_log rows carry `phase = 'job:<name>'`.
- : await withSubmissionAuthority(authority, () => withChatPhase(`job:${job.name}`, () => runWithJobSpend(this.engine, job, context as MinionJobContext, handler)), abort.signal);
+ : await withEngineScope(this.engine, () => withSubmissionAuthority(authority, () => withChatPhase(`job:${job.name}`, () => runWithJobSpend(this.engine, job, context as MinionJobContext, handler)), abort.signal));
// The child spawned and ran — the spawn path is healthy again.
this._consecutiveChildSpawnFailures = 0;
diff --git a/src/core/search/hybrid.ts b/src/core/search/hybrid.ts
index b194b189fd..0285ef9be8 100644
--- a/src/core/search/hybrid.ts
+++ b/src/core/search/hybrid.ts
@@ -53,6 +53,7 @@ import { searchVectorFallback, searchWithoutEmbeddings } from './hybrid/keyword-
import { factEmbeddingDisabled } from '../embedding-disabled.ts';
import { capSessionPool, collapsePool, expandStructuralNeighbors, finalizeHybridResults, fuseArms, rerankAndPin, sizeReturnPool } from './hybrid/rank.ts';
import { type StageTimer, UNTIMED } from './stage-timings.ts';
+import { needsEngineScope, withEngineScope } from '../engine-scope.ts';
export const RRF_K = 60;
const COMPILED_TRUTH_BOOST = 2.0;
@@ -1080,6 +1081,7 @@ export async function hybridSearch(
query: string,
opts?: HybridSearchOpts,
): Promise<SearchResult[]> {
+ if (needsEngineScope(engine)) return withEngineScope(engine, () => hybridSearch(engine, query, opts));
if (opts?.types?.length === 0) return [];
const timer = opts?._timings ?? UNTIMED;
if (opts?.type || opts?.types?.length) {
@@ -1205,6 +1207,7 @@ export async function hybridSearchCached(
query: string,
opts?: HybridSearchOpts,
): Promise<SearchResult[]> {
+ if (needsEngineScope(engine)) return withEngineScope(engine, () => hybridSearchCached(engine, query, opts));
if (opts?.types?.length === 0) return [];
const timer = opts?._timings ?? UNTIMED;
const { modeInputForCache, resolvedForCache, knobsHash } = await timer.stage('setup', () => resolveCacheSearchMode(engine, opts));
diff --git a/test/engine-scope-entry-points.test.ts b/test/engine-scope-entry-points.test.ts
new file mode 100644
index 0000000000..f7c5ec4b3f
--- /dev/null
+++ b/test/engine-scope-entry-points.test.ts
@@ -0,0 +1,90 @@
+/**
+ * GBRA-283 B3a (N1): the engine-taking entry points a host calls enter the engine's scope themselves when the engine
+ * was opened from settings (hybridSearch, the import paths), and the minion worker runs each job in its engine's
+ * scope. A host that never wraps them in withEngineScope still gets that engine's providers, and never the process
+ * gateway or engine_scope_required. Every provider is a transport stub.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { __setEmbedTransportForTests, configureGateway, embedQuery, resetGateway } from '../src/core/ai/gateway.ts';
+import { openEngine, type EngineSettings } from '../src/core/engine-open.ts';
+import { embeddedEngineInScope } from '../src/core/engine-scope.ts';
+import { importFromContent } from '../src/core/import-file.ts';
+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';
+
+const EMBEDDING = { model: 'openai:text-embedding-3-small', dimensions: 1536 };
+const key = (label: string) => `sk-${label}-${randomBytes(12).toString('hex')}`;
+const settingsFor = (apiKey: string): EngineSettings => ({
+ embedded_core: true, engine: 'pglite', database: {}, host: { id: randomUUID() }, embedding: EMBEDDING, ai: { providers: { openai: { apiKey } } },
+});
+const PROCESS_KEY = key('process');
+const sent: string[] = [];
+function installEmbedStub(): void {
+ __setEmbedTransportForTests((async ({ model, values }: any) => {
+ const headers = await model.config.headers();
+ sent.push(headers.authorization ?? headers.Authorization ?? '');
+ return { embeddings: values.map(() => Array.from({ length: EMBEDDING.dimensions }, (_, i) => (i % 7) + 1)), usage: { tokens: 1 } };
+ }) as any);
+ configureGateway({ embedding_model: EMBEDDING.model, embedding_dimensions: EMBEDDING.dimensions, env: { OPENAI_API_KEY: PROCESS_KEY } });
+}
+
+afterEach(() => {
+ sent.length = 0;
+ __setEmbedTransportForTests(null);
+ resetGateway();
+});
+
+describe('entry points a host calls without a scope', () => {
+ test('import and search on an embedded engine embed with that engine\'s key', async () => {
+ installEmbedStub();
+ const keyA = key('a');
+ const a = await openEngine(settingsFor(keyA));
+ const b = await openEngine(settingsFor(key('b')));
+ try {
+ await a.initSchema();
+ await importFromContent(a, 'notes/alpha-example', '# Alpha\n\nA note about acme-example and its quarterly plan for brain-a.');
+ expect(sent.length).toBeGreaterThan(0);
+ expect(new Set(sent)).toEqual(new Set([`Bearer ${keyA}`]));
+ sent.length = 0;
+ await hybridSearch(a, 'quarterly plan');
+ await hybridSearchCached(a, 'acme-example plan');
+ expect(sent.length).toBeGreaterThan(0);
+ expect(new Set(sent)).toEqual(new Set([`Bearer ${keyA}`]));
+ } finally {
+ await Promise.all([a.disconnect(), b.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');
+ const a = await openEngine(settingsFor(keyA));
+ const b = await openEngine(settingsFor(key('b')));
+ try {
+ await a.initSchema();
+ const queue = new MinionQueue(a);
+ const job = await queue.add('scope-probe', {});
+ const worker = new MinionWorker(a, { concurrency: 1, pollInterval: 20, healthCheckInterval: 0, stalledInterval: 60_000 });
+ worker.register('scope-probe', async () => {
+ await embedQuery('from a job');
+ return { inScope: embeddedEngineInScope() === a };
+ });
+ const running = worker.start();
+ try {
+ await waitFor(async () => ['completed', 'failed', 'dead'].includes((await queue.getJob(job.id))?.status ?? ''), { timeoutMs: 30_000, label: 'probe settled' });
+ } finally {
+ worker.stop();
+ await running;
+ }
+ const done = await queue.getJob(job.id);
+ expect([done?.status, done?.error_text ?? null]).toEqual(['completed', null]);
+ expect(done?.result).toEqual({ inScope: true });
+ expect(sent).toEqual([`Bearer ${keyA}`]);
+ } finally {
+ await Promise.all([a.disconnect(), b.disconnect()]);
+ }
+ }, 120_000);
+});