Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(embedded): unscoped AI calls refuse engine_scope_required by scope presence alone (B3a A)

garrytan4880911ba7e8
diff --git a/src/cli.ts b/src/cli.ts
index 21d1c729f9..6c191a0a3a 100755
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -16,6 +16,7 @@ import { agentJsonGuardMode } from './cli/json-guard.ts';
import { parseGlobalFlags } from './core/cli-options.ts';
import { runCliPreflight } from './core/cli-preflight.ts';
import { printHelp } from './cli/top-help.ts';
+import { withLocalScope } from './core/engine-scope-store.ts';
/**
* The fast path main() would take for `argv`, or null when the dispatcher must
@@ -56,11 +57,11 @@ if (import.meta.main) {
if (shouldForceExitAfterMain()) installStdoutPipeDelivery(agentJsonGuardMode(process.argv.slice(2)));
const fastPath = cliFastPath(process.argv.slice(2));
if (fastPath) {
- runFastPath(fastPath).then(
+ withLocalScope(() => runFastPath(fastPath)).then(
() => flushThenExit(currentExitCode()),
async (e) => (await import('./cli/main.ts')).exitOnFatalCliError(e),
);
} else {
- void import('./cli/main.ts').then((m) => m.runCli());
+ void withLocalScope(() => import('./cli/main.ts').then((m) => m.runCli()));
}
}
diff --git a/src/commands/jobs.ts b/src/commands/jobs.ts
index f90aacdd73..bdd311ef1d 100644
--- a/src/commands/jobs.ts
+++ b/src/commands/jobs.ts
@@ -53,6 +53,7 @@ import { runJobsWork } from './jobs/work.ts';
import { runJobsSupervisor } from './jobs/supervisor.ts';
import { runJobsWatch } from './jobs/watch.ts';
import type { JobsCommandContext } from './jobs/shared.ts';
+import { withLocalScope } from '../core/engine-scope-store.ts';
// Moved to src/core/minions/handlers/ (refactor wave 1); re-exported so importers keep this path.
export { resolveJobPull } from '../core/minions/handlers/job-pull.ts';
@@ -464,7 +465,12 @@ const JOBS_SUBCOMMANDS: Record<string, (ctx: JobsCommandContext) => Promise<void
watch: runJobsWatch,
};
-export async function runJobs(engineOrNull: BrainEngine | null, args: string[]): Promise<void> {
+/** `gbrain jobs` (the worker included) runs in a local scope, so its own AI calls use the process gateway (engine-scope.ts). */
+export function runJobs(engineOrNull: BrainEngine | null, args: string[]): Promise<void> {
+ return withLocalScope(() => runJobsCommand(engineOrNull, args));
+}
+
+async function runJobsCommand(engineOrNull: BrainEngine | null, args: string[]): Promise<void> {
const sub = args[0];
// Help guards run BEFORE the thin-client refusal below: cli.ts routes
diff --git a/src/commands/serve-http.ts b/src/commands/serve-http.ts
index ecead26fc4..b101a9b643 100644
--- a/src/commands/serve-http.ts
+++ b/src/commands/serve-http.ts
@@ -54,6 +54,7 @@ import { registerCleanup } from '../core/process-cleanup.ts';
import { VERSION } from '../version.ts';
import { NoticeLedger } from '../core/notice-ledger.ts';
import { createReadinessCache, type ReadinessCache } from '../core/readiness.ts';
+import { withLocalScope } from '../core/engine-scope-store.ts';
export { extractGitHubItemRef, githubKindCoversRepo, selectGitHubItemSources } from './serve-http-webhooks.ts';
export { HEALTH_TIMEOUT_MS, probeHealth, probeLiveness, type ProbeHealthResult } from './serve-http-metrics.ts';
@@ -843,7 +844,12 @@ export async function buildServeHttpApp(app: express.Express, engine: BrainEngin
return { bind, config, sql, issuerUrl, skillStatus, bootstrapToken, bootstrapFromEnv, suppressBootstrapPrint };
}
-export async function runServeHttp(engine: BrainEngine, options: ServeHttpOptions) {
+/** The HTTP server runs in a local scope; each POST /mcp enters its engine's scope (serve-http-mcp.ts). */
+export function runServeHttp(engine: BrainEngine, options: ServeHttpOptions) {
+ return withLocalScope(() => serveHttp(engine, options));
+}
+
+async function serveHttp(engine: BrainEngine, options: ServeHttpOptions) {
const { port, tokenTtl, enableDcr, enableDcrInsecure } = options;
// Express 5 app
const app = express();
diff --git a/src/commands/serve.ts b/src/commands/serve.ts
index b9956ebe0d..1f46f9e082 100644
--- a/src/commands/serve.ts
+++ b/src/commands/serve.ts
@@ -17,6 +17,7 @@ import { isReadOnlyServeArgs, readOnlyServeSkipsResidentDuties } from '../core/d
import { onForwardProgress } from '../core/forward-progress.ts';
import { foregroundWindow } from '../core/foreground-activity.ts';
import { graduationHandoffRequested, writeServeGraduationEnvelope } from '../core/persistence/graduation-serve-guard.ts';
+import { withLocalScope } from '../core/engine-scope-store.ts';
import {
installLoopStallWatchdog,
resolveServeStallWatchdogMs,
@@ -233,10 +234,15 @@ export async function finishHttpServe(
exitOnce(0);
}
-export async function runServe(
+/** gbrain serve (stdio and --http) runs in a local scope, so its own AI calls use the process gateway (engine-scope.ts). */
+export function runServe(engine: BrainEngine, args: string[] = [], opts: ServeOptions = {}) {
+ return withLocalScope(() => serveBrain(engine, args, opts));
+}
+
+async function serveBrain(
engine: BrainEngine,
- args: string[] = [],
- opts: ServeOptions = {},
+ args: string[],
+ opts: ServeOptions,
) {
// v0.26+: --http dispatches to the full OAuth 2.1 server (serve-http.ts)
// with admin dashboard, scope enforcement, SSE feed, and the requireBearerAuth
diff --git a/src/core/ai/anthropic-key.ts b/src/core/ai/anthropic-key.ts
index a097c60a99..ac24d6852d 100644
--- a/src/core/ai/anthropic-key.ts
+++ b/src/core/ai/anthropic-key.ts
@@ -26,7 +26,7 @@
import { loadConfig } from '../config.ts';
import { embeddedSettingsRecord } from '../embedded-engine.ts';
import { embeddedEngineInScope, unscopedInEmbeddedProcess } from '../engine-scope.ts';
-import { engineScopeMissing, engineScopeUnentered } from './engine-gateway.ts';
+import { engineScopeMissing, engineScopeRequired } from './engine-gateway.ts';
/** In an embedded engine's scope (engine-scope.ts): its own `settings.ai` Anthropic key, or null. Undefined outside one. */
function engineAnthropicKey(): string | null | undefined {
@@ -43,8 +43,6 @@ function engineAnthropicKey(): string | null | undefined {
* `ANTHROPIC_API_KEY`). Cleared by the gateway reset paths via the stash.
*/
let _gatewayEnvKeySnapshot: string | undefined;
-/** Whether `configureGateway()` set a process gateway: in a process holding embedded engines, only then may an unscoped call use process keys. */
-let _processGatewayConfigured = false;
/**
* Push seam for `configureGateway()`: stash the gateway env's Anthropic key
@@ -59,7 +57,6 @@ export function stashGatewayAnthropicKeyFromEnv(
): void {
const key = env?.ANTHROPIC_API_KEY;
_gatewayEnvKeySnapshot = key !== process.env.ANTHROPIC_API_KEY ? key : undefined;
- _processGatewayConfigured = env !== undefined;
}
/**
@@ -89,7 +86,7 @@ export function getGatewayAnthropicKeySnapshot(): string | undefined {
*/
export function anthropicClientOptions(): { apiKey?: string; baseURL?: string } {
const engine = embeddedEngineInScope();
- if (!engine && unscopedInEmbeddedProcess() && !_processGatewayConfigured) throw engineScopeUnentered();
+ if (!engine && unscopedInEmbeddedProcess()) throw engineScopeRequired();
if (!engine) return { apiKey: resolveAnthropicKey() };
const provider = embeddedSettingsRecord(engine)?.ai?.providers.anthropic;
if (!provider?.apiKey) throw engineScopeMissing('anthropic', 'chat');
@@ -111,7 +108,7 @@ export function hasAnthropicKey(): boolean {
export function resolveAnthropicKey(): string | undefined {
const scoped = engineAnthropicKey();
if (scoped !== undefined) return scoped ?? undefined;
- if (unscopedInEmbeddedProcess() && !_processGatewayConfigured) return undefined;
+ if (unscopedInEmbeddedProcess()) return undefined;
if (process.env.ANTHROPIC_API_KEY) return process.env.ANTHROPIC_API_KEY;
if (_gatewayEnvKeySnapshot) return _gatewayEnvKeySnapshot;
try {
diff --git a/src/core/ai/engine-gateway.ts b/src/core/ai/engine-gateway.ts
index 64ce38374a..dc3fe030d7 100644
--- a/src/core/ai/engine-gateway.ts
+++ b/src/core/ai/engine-gateway.ts
@@ -113,10 +113,13 @@ export function releasedKeyEnv(): Record<string, string> {
return Object.fromEntries((engine ? releasedEngineKeys(engine) : []).map((value, i) => [`RELEASED_${i}_API_KEY`, value]));
}
-/** The refusal for an AI call made outside any engine scope in a process holding embedded engines whose host configured no process gateway. */
-export function engineScopeUnentered(): Error {
- return opError('engine_scope_missing', 'An AI call ran outside any engine scope in a process that holds engines opened from settings.',
- 'Its brain is unknown, so no process.env key, ~/.gbrain/config.json or default gateway is used and nothing was sent. Run it inside withEngineScope(engine, fn), or configure a process gateway (configureGateway) for calls that belong to no engine.');
+/**
+ * The refusal for an AI call that entered no scope in a process holding open embedded engines. It decides by scope
+ * presence alone: a process gateway the host configured never opens it.
+ */
+export function engineScopeRequired(): Error {
+ return opError('engine_scope_required', 'An AI call ran outside any engine scope in a process that holds engines opened from settings.',
+ 'Its brain is unknown, so no process.env key, ~/.gbrain/config.json or process gateway is used and nothing was sent. Run it inside withEngineScope(engine, fn) for the engine it belongs to, or withLocalScope(fn) for a call that belongs to the process gateway.');
}
/** In an embedded engine's scope, its settings.ai.models.reranker; search uses it in place of the mode bundle's default. */
diff --git a/src/core/ai/gateway.ts b/src/core/ai/gateway.ts
index bf4f7e6814..12c8ce0309 100644
--- a/src/core/ai/gateway.ts
+++ b/src/core/ai/gateway.ts
@@ -65,7 +65,7 @@ import type { BrainEngine } from '../engine.ts';
import { dimsProviderOptions } from './dims.ts';
import { hasAnthropicKey, stashGatewayAnthropicKeyFromEnv } from './anthropic-key.ts';
import { unscopedInEmbeddedProcess, withEngineScope } from '../engine-scope.ts';
-import { engineScopeMissing, engineScopeUnentered, releasedKeyEnv, scopedGatewayState, type GatewayState } from './engine-gateway.ts';
+import { engineScopeMissing, engineScopeRequired, releasedKeyEnv, scopedGatewayState, type GatewayState } from './engine-gateway.ts';
import { AIConfigError, AITransientError, isStructuredOutputRejection, isUnbilledEmbeddingRejection, normalizeAIError } from './errors.ts';
import { embeddingModelNotFoundHint, gatewayModelNotFoundHint } from './model-not-found-hint.ts';
import { fitMatryoshkaPrefix, isEmbeddingZeroNormError, screenAlignedEmbeddings, screenEmbeddings, sendableEmbeddingInputs } from './embedding-guard.ts';
@@ -141,9 +141,16 @@ const DEFAULT_CHAT_MODEL = 'anthropic:claude-sonnet-4-6';
/** What `configureGateway` writes and every call reads, except a call in an embedded engine's scope (engine-gateway.ts). */
const processState: GatewayState = { config: null, modelCache: new Map(), cacheTag: '' };
-const gw = (): GatewayState => scopedGatewayState(gatewayConfigOf) ?? processState;
+/** A call with no scope in a process holding open embedded engines: no config and no provider, so every read of it refuses or reads as unavailable. */
+const unscopedState: GatewayState = { config: null, modelCache: new Map(), providers: new Set(), cacheTag: '' };
+const gw = (): GatewayState => scopedGatewayState(gatewayConfigOf) ?? (unscopedInEmbeddedProcess() ? unscopedState : processState);
+/** Every AI call starts here: with no scope in a process holding open embedded engines it refuses `engine_scope_required`. */
+function refuseUnscoped(): void {
+ if (unscopedInEmbeddedProcess()) throw engineScopeRequired();
+}
/** The config a call to `recipe` uses; an embedded engine not given that provider refuses `engine_scope_missing`. */
function configFor(recipe: Recipe, touchpoint: string): AIGatewayConfig {
+ refuseUnscoped();
const { providers } = gw();
if (providers && !providers.has(recipe.id)) throw engineScopeMissing(recipe.id, touchpoint);
return requireConfig();
@@ -172,7 +179,7 @@ export function authToHeaders(auth: { apiKey?: string; headers?: Record<string,
* are deliberately left unchanged.
*/
export function configureGatewayIfUninitialized(): void {
- if (processState.config || gw() !== processState || unscopedInEmbeddedProcess()) return;
+ if (processState.config || gw() !== processState) return;
const config = loadConfig();
if (config) configureGateway(buildGatewayConfig(config));
}
@@ -842,9 +849,9 @@ export function __setChatTransportForTests(
* `models doctor` base-URL probe (which reads the same merged config the
* gateway calls with, inside its own fail-open guard). */
export function requireConfig(): AIGatewayConfig {
+ refuseUnscoped();
const config = gw().config;
if (!config) {
- if (unscopedInEmbeddedProcess()) throw engineScopeUnentered();
throw new AIConfigError(
'AI gateway is not configured. Call configureGateway() during engine connect.',
'This is a gbrain bug — file an issue at https://github.com/garrytan/gbrain/issues',
@@ -1620,6 +1627,7 @@ export interface EmbedOpts {
}
export async function embed(texts: string[], opts?: EmbedOpts): Promise<Float32Array[]> {
+ refuseUnscoped();
if (!texts || texts.length === 0) return [];
const cfg = requireConfig();
@@ -1915,6 +1923,7 @@ export async function embedMultimodal(
inputs: MultimodalInput[],
opts: EmbedMultimodalOpts = {},
): Promise<Float32Array[]> {
+ refuseUnscoped();
if (!inputs || inputs.length === 0) return [];
// Fix wave 13 P1.18: reserve on the ambient tracker before any provider call,
// as embed() does. An image is reserved at the provider's per-input maximum
@@ -2512,6 +2521,7 @@ function normalizeSdkUsage(usage: unknown): { inputTokens: number; outputTokens:
* Caller is responsible for sanitizing the query (prompt-injection boundary stays in expansion.ts).
*/
export async function expand(query: string): Promise<string[]> {
+ refuseUnscoped();
if (!query || !query.trim()) return [query];
if (!isAvailable('expansion')) return [query];
@@ -3569,6 +3579,7 @@ export function toAISDKTools(tools: ChatToolDef[] | undefined): Record<string, a
}
export async function chat(opts: ChatOpts): Promise<ChatResult> {
+ refuseUnscoped();
await discoverBeforeOpenAICall(opts.model ?? gw().config?.chat_model);
const fallbackChain = opts.allowFallback === false ? undefined : gw().config?.chat_fallback_chain;
if (fallbackChain?.length) return chatWithFallback(opts, opts.model ?? getChatModel(), fallbackChain, chat, { onRefusal: gw().config?.chat_fallback_on_refusal !== false });
@@ -4044,6 +4055,7 @@ export interface ToolLoopResult {
* via `__setChatTransportForTests` without any DB.
*/
export async function toolLoop(opts: ToolLoopOpts): Promise<ToolLoopResult> {
+ refuseUnscoped();
const maxTurns = opts.maxTurns ?? 20;
const maxTokens = opts.maxTokens ?? defaultMaxOutputTokens(opts.model ?? getChatModel());
const handlers = opts.toolHandlers;
@@ -4339,6 +4351,7 @@ export function __setRerankTransportForTests(fn: RerankTransport | null): void {
const DEFAULT_RERANK_TIMEOUT_MS = 5000;
export async function rerank(input: RerankInput): Promise<RerankResult[]> {
+ refuseUnscoped();
if (!input.query) {
throw new RerankError('rerank: query is required', 'unknown');
}
diff --git a/src/core/engine-open.ts b/src/core/engine-open.ts
index e6f6205695..6de12a389c 100644
--- a/src/core/engine-open.ts
+++ b/src/core/engine-open.ts
@@ -14,7 +14,7 @@ import { getRecipe } from './ai/recipes/index.ts';
export type { EngineAISettings, EngineSettings, EmbeddedSettingsView } from './embedded-engine.ts';
export { embeddedSettings, isEmbeddedEngine, processHasEmbeddedEngines } from './embedded-engine.ts';
-export { withEngineScope } from './engine-scope.ts';
+export { withEngineScope, withLocalScope } from './engine-scope.ts';
export { hostIdFor } from './persistence/identity.ts';
/** Connections a Postgres engine opened from settings may open when `pool.max` is not given. */
diff --git a/src/core/engine-scope-store.ts b/src/core/engine-scope-store.ts
new file mode 100644
index 0000000000..2daeceb2b6
--- /dev/null
+++ b/src/core/engine-scope-store.ts
@@ -0,0 +1,14 @@
+/**
+ * The store engine-scope.ts reads, and the local scope the CLI, gbrain serve and the jobs worker enter at their entry
+ * points. A leaf (no imports beyond node), so the CLI entry pays nothing to enter it.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export const engineScopeStore = new AsyncLocalStorage<object>();
+
+const LOCAL = Object.freeze({});
+
+/** Runs `fn` as a call that belongs to no embedded engine: its AI calls use the process gateway, as before embedded engines existed. */
+export function withLocalScope<T>(fn: () => T): T {
+ return engineScopeStore.run(LOCAL, fn);
+}
diff --git a/src/core/engine-scope.ts b/src/core/engine-scope.ts
index b19810da64..d211e3dd45 100644
--- a/src/core/engine-scope.ts
+++ b/src/core/engine-scope.ts
@@ -2,21 +2,29 @@
* Which engine a call runs for, for code that reads per-engine state without taking the engine as an argument: the
* AI gateway (ai/gateway.ts) and the Anthropic key resolver (ai/anthropic-key.ts). Every operation handler runs inside
* its context's engine scope (operation-load.ts), and so does each persistence consumer (persistence/service.ts).
- * A host that calls core functions directly, outside an operation, wraps them in `withEngineScope(engine, fn)`.
+ * A host that calls core functions directly, outside an operation, wraps them in `withEngineScope(engine, fn)`; the
+ * engine-taking entry points a host calls (hybridSearch, the import paths) enter it themselves (needsEngineScope).
*
- * Only an engine `openEngine` opened changes anything: for every other engine, and in a process that never opened
- * one, the gateway keeps its process-wide state exactly as before, and no scope is even entered.
+ * 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.
*/
-import { AsyncLocalStorage } from 'node:async_hooks';
import { isEmbeddedEngine, processHasEmbeddedEngines, processHoldsEmbeddedEngines } from './embedded-engine.ts';
+import { engineScopeStore as scope } from './engine-scope-store.ts';
-const scope = new AsyncLocalStorage<object>();
+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. */
export function withEngineScope<T>(engine: object, fn: () => T): T {
return processHasEmbeddedEngines() ? scope.run(engine, fn) : 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. */
+export function needsEngineScope(engine: object): boolean {
+ return isEmbeddedEngine(engine) && scope.getStore() !== engine;
+}
+
/** The engine scope the current call runs in, for deferred work to resume in with runInEngineScope. */
export function currentEngineScope(): object | undefined {
return scope.getStore();
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index 566633a0db..1df67767e2 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -304,7 +304,8 @@ export const CODES = {
engine_embedding_mismatch: { class: 'host_only', actor: 'user', summary: "An engine opened from settings names an embedding model or width that differs from the one its database already records, so initSchema changed nothing.", why: 'The vector column has one width and the brain one embedding model; seeding another over it would make every stored and future embedding unreadable. Changing it is an explicit re-embed the user decides on.', docs: 'docs/ENGINES.md#opening-an-engine-from-settings-experimental', suggestion: "Pass the database's recorded model and width in settings.embedding, or read the recorded identity with gbrain migrate embeddings --status on the brain host and preview a migration from there.", fix: { argv: ['gbrain', 'migrate', 'embeddings', '--status', '--json'], consent: [], actor: 'agent', requires_exclusive: false, why: "Read-only: reports the brain's recorded embedding model and width and what a migration would change." } },
engine_closed: { class: 'caller', summary: 'An engine opened from settings was disconnected, which closes it for good, so connect() and reconnect() refuse and nothing was reopened.', docs: 'docs/ENGINES.md#opening-an-engine-from-settings-experimental', suggestion: 'Call openEngine again with the settings to open a new engine.' },
engine_host_missing: { class: 'caller', summary: "An engine opened from settings has no host identity, so nothing that needs one ran and no host.json was created.", why: 'An embedded engine publishes and claims work under the host id its host gave at open; minting a host.json under the home directory instead would tie its writes to whatever process happens to share that directory.', docs: 'docs/ENGINES.md#opening-an-engine-from-settings-experimental', suggestion: 'Pass host: { id: <uuid> } to openEngine; keep the same id for the same host across restarts.' },
- engine_scope_missing: { class: 'caller', summary: "An engine opened from settings made an AI call (embed, chat, expansion or rerank) through a provider its settings.ai does not name, or a call ran outside any engine scope in a process holding such engines, so nothing was sent.", why: "An embedded engine's AI calls reach only the providers and keys its host passed as values. Falling back to a process.env key, ~/.gbrain/config.json or the process-wide gateway would spend another brain's key and send this brain's text where its host never pointed it.", docs: 'docs/ENGINES.md#opening-an-engine-from-settings-experimental', suggestion: 'Pass the provider in settings.ai.providers (apiKey, and baseUrl when it is not the default) to openEngine, or point settings.ai.models (or settings.embedding) at a provider the engine has.' },
+ engine_scope_missing: { class: 'caller', summary: "An engine opened from settings made an AI call (embed, chat, expansion or rerank) through a provider its settings.ai does not name, or after it was disconnected, so nothing was sent.", why: "An embedded engine's AI calls reach only the providers and keys its host passed as values. Falling back to a process.env key, ~/.gbrain/config.json or the process-wide gateway would spend another brain's key and send this brain's text where its host never pointed it.", docs: 'docs/ENGINES.md#opening-an-engine-from-settings-experimental', suggestion: 'Pass the provider in settings.ai.providers (apiKey, and baseUrl when it is not the default) to openEngine, or point settings.ai.models (or settings.embedding) at a provider the engine has.' },
+ engine_scope_required: { class: 'caller', summary: "An AI call (embed, chat, expansion or rerank) ran outside any engine scope while this process holds engines opened from settings, so nothing was sent.", why: "With no scope the call's brain is unknown. Using the process gateway, a process.env key or ~/.gbrain/config.json would spend a key no brain's host gave and could send one brain's text where its host never pointed it, so the call refuses whatever process gateway the host configured.", docs: 'docs/ENGINES.md#opening-an-engine-from-settings-experimental', suggestion: 'Run the call inside withEngineScope(engine, fn) for the engine it belongs to, or withLocalScope(fn) for a call that belongs to the process gateway (both exported from gbrain/engine-open).' },
engine_settings_invalid: { class: 'caller', summary: "A setting passed to openEngine is missing or malformed (engine kind, database url or path, pool size, host or writer id, writer credential or lane, embedding identity), so nothing was opened or registered.", docs: 'docs/ENGINES.md#opening-an-engine-from-settings-experimental', suggestion: 'Correct the setting the message names and call again.' },
engine_graduated: { class: 'caller', summary: "A client opened a PGLite brain that moved to Postgres; its old path holds a tombstone.", docs: 'docs/guides/move-to-postgres.md#graduated-datastore' },
// wave 18b (GBRA-106) #4772: onboarding coverage checks read entity types from the active pack(s).
diff --git a/test/engine-gateway.test.ts b/test/engine-gateway.test.ts
index a72acc9742..a6e589ac68 100644
--- a/test/engine-gateway.test.ts
+++ b/test/engine-gateway.test.ts
@@ -23,7 +23,7 @@ import { resolveSearchMode } from '../src/core/search/mode.ts';
import { DEFAULT_RERANKER_MODEL } from '../src/core/ai/defaults.ts';
import type { MinionJobContext } from '../src/core/minions/types.ts';
import { startPersistenceConsumer, stopPersistenceConsumer } from '../src/core/persistence/service.ts';
-import { embeddedSettings, openEngine, withEngineScope, type EngineSettings } from '../src/core/engine-open.ts';
+import { embeddedSettings, openEngine, withEngineScope, withLocalScope, type EngineSettings } from '../src/core/engine-open.ts';
import { createEngine } from '../src/core/engine-factory.ts';
import { createDegradedEngine } from '../src/core/degraded-engine.ts';
import { operationsByName, type OperationContext } from '../src/core/operations.ts';
@@ -236,7 +236,7 @@ describe('process base URLs never reach an engine', () => {
expect(withEngineScope(proxied, () => new Anthropic(anthropicClientOptions())).baseURL).toBe('https://engine-proxy.example');
const error = await withEngineScope(without, () => failure(async () => anthropicClientOptions()));
expect(error?.code).toBe('engine_scope_missing');
- expect(anthropicClientOptions()).toEqual({ apiKey: PROCESS_KEY });
+ expect(withLocalScope(() => anthropicClientOptions())).toEqual({ apiKey: PROCESS_KEY });
} finally {
await Promise.all([named.disconnect(), proxied.disconnect(), without.disconnect()]);
}
@@ -285,7 +285,7 @@ describe('chat usage and unscoped calls', () => {
const usageRows = async (engine: BrainEngine) => Number((await engine.executeRaw<{ n: number }>('SELECT count(*)::int AS n FROM chat_usage_log'))[0]!.n);
const settled = () => Bun.sleep(200);
- test('chat usage lands in the in-scope engine\'s database, and an unscoped call never books to an embedded engine', async () => {
+ test('chat usage lands in the in-scope engine\'s database, and a local-scope call never books to an embedded engine', async () => {
installStubs();
configureProcessGateway();
const cli = await createEngine({ engine: 'pglite' });
@@ -299,7 +299,7 @@ describe('chat usage and unscoped calls', () => {
await withEngineScope(a, () => chat({ messages: [{ role: 'user', content: 'hello from a' }] }));
await settled();
expect([await usageRows(a), await usageRows(b), await usageRows(cli)]).toEqual([1, 0, 0]);
- await chat({ messages: [{ role: 'user', content: 'hello from the host' }] });
+ await withLocalScope(() => chat({ messages: [{ role: 'user', content: 'hello from the host' }] }));
await settled();
expect([await usageRows(a), await usageRows(b), await usageRows(cli)]).toEqual([1, 0, 1]);
} finally {
@@ -307,20 +307,22 @@ describe('chat usage and unscoped calls', () => {
}
}, 120_000);
- test('a process holding an embedded engine refuses an unscoped AI call unless the host configured a process gateway', async () => {
+ test('a process holding an embedded engine refuses an unscoped AI call engine_scope_required, also with a process gateway; a local scope uses it', async () => {
__unconfigureGatewayForTests();
installStubs();
await withEnv(ambient, async () => {
const engine = await openEngine(settingsFor({ ai: { providers: { openai: { apiKey: key('a') } } } }));
try {
const error = await failure(() => chat({ messages: [{ role: 'user', content: 'hello' }] }));
- expect(error?.code).toBe('engine_scope_missing');
+ expect(error?.code).toBe('engine_scope_required');
expect(`${error!.message} ${error!.suggestion}`).toContain('withEngineScope');
expect(resolveAnthropicKey()).toBeUndefined();
- expect((await failure(async () => anthropicClientOptions()))?.code).toBe('engine_scope_missing');
+ expect((await failure(async () => anthropicClientOptions()))?.code).toBe('engine_scope_required');
configureProcessGateway();
- expect(await failure(() => chat({ messages: [{ role: 'user', content: 'hello' }] }))).toBeNull();
- expect(resolveAnthropicKey()).toBe(PROCESS_KEY);
+ expect((await failure(() => chat({ messages: [{ role: 'user', content: 'hello' }] })))?.code).toBe('engine_scope_required');
+ expect(resolveAnthropicKey()).toBeUndefined();
+ expect(await withLocalScope(() => failure(() => chat({ messages: [{ role: 'user', content: 'hello' }] })))).toBeNull();
+ expect(withLocalScope(resolveAnthropicKey)).toBe(PROCESS_KEY);
} finally {
await engine.disconnect();
}
@@ -344,7 +346,7 @@ describe('facts queue', () => {
const job = async () => { await chat({ messages: [{ role: 'user', content: 'extract facts' }] }); };
withEngineScope(first!, () => queue.enqueue(job, 'shared-session'));
withEngineScope(second!, () => queue.enqueue(job, 'shared-session'));
- queue.enqueue(job, 'shared-session');
+ withLocalScope(() => queue.enqueue(job, 'shared-session'));
expect((await queue.drainPending({ timeout: 30_000 })).unfinished).toBe(0);
expect(sent.filter(s => s.kind === 'chat').map(s => s.auth)).toEqual([`Bearer ${keyOf(first!)}`, `Bearer ${keyOf(second!)}`, `Bearer ${PROCESS_KEY}`]);
}
@@ -507,7 +509,8 @@ describe('an engine that openEngine did not open', () => {
const cli = await createEngine({ engine: 'pglite' });
try {
expect(await withEngineScope(cli, snapshot)).toBe(outside);
- expect(await snapshot()).toBe(outside);
+ expect(await withLocalScope(snapshot)).toBe(outside);
+ expect((await failure(snapshot))?.code).toBe('engine_scope_required');
expect(await withEngineScope(embedded, snapshot)).not.toBe(outside);
} finally {
await embedded.disconnect();
diff --git a/test/engine-scope-required.test.ts b/test/engine-scope-required.test.ts
new file mode 100644
index 0000000000..a427e5db0f
--- /dev/null
+++ b/test/engine-scope-required.test.ts
@@ -0,0 +1,168 @@
+/**
+ * GBRA-283 B3a: in a process that holds engines opened from settings, an AI call decides by scope presence alone. In an
+ * embedded engine's scope it uses that engine's providers; in a local scope (withLocalScope, entered by the CLI, gbrain
+ * serve and the jobs worker, or a non-embedded engine's scope) it uses the process gateway; with no scope at all it
+ * refuses engine_scope_required, whatever process gateway the host configured. Every provider is a transport stub.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes, randomUUID } from 'node:crypto';
+import {
+ __setEmbedTransportForTests, __setGenerateObjectTransportForTests, __setGenerateTextTransportForTests, __setRerankTransportForTests, __unconfigureGatewayForTests,
+ chat, configureGateway, configureGatewayIfUninitialized, embed, embedQuery, expand, requireConfig, rerank, resetGateway,
+} from '../src/core/ai/gateway.ts';
+import { anthropicClientOptions, resolveAnthropicKey } from '../src/core/ai/anthropic-key.ts';
+import { openEngine, withEngineScope, withLocalScope, type EngineSettings } from '../src/core/engine-open.ts';
+import { createEngine } from '../src/core/engine-factory.ts';
+import type { BrainEngine } from '../src/core/engine.ts';
+import { withEnv } from './helpers/with-env.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 }, voyage: { apiKey } }, models: { chat: 'openai:gpt-5.6', expansion: 'openai:gpt-5.6' } },
+});
+const failure = async (work: () => unknown) => {
+ try { await work(); return null; } catch (error) { return error as Error & { code?: string; suggestion?: string }; }
+};
+
+type Sent = { kind: string; auth: string | null };
+const sent: Sent[] = [];
+async function sentBy(kind: string, model: any): Promise<void> {
+ const headers = await model.config.headers();
+ sent.push({ kind, auth: headers.authorization ?? headers.Authorization ?? headers['x-api-key'] ?? null });
+}
+function installStubs(): void {
+ __setEmbedTransportForTests((async ({ model, values }: any) => {
+ await sentBy('embed', model);
+ return { embeddings: values.map(() => Array.from({ length: EMBEDDING.dimensions }, (_, i) => (i % 7) + 1)), usage: { tokens: 1 } };
+ }) as any);
+ __setGenerateTextTransportForTests((async ({ model }: any) => {
+ await sentBy('chat', model);
+ return { content: [{ type: 'text', text: 'ok' }], text: '{"queries":[]}', finishReason: 'stop', usage: { inputTokens: 1, outputTokens: 1 } };
+ }) as any);
+ __setGenerateObjectTransportForTests((async ({ model }: any) => {
+ await sentBy('expand', model);
+ return { object: { queries: ['alternative'] }, usage: { inputTokens: 1, outputTokens: 1 } };
+ }) as any);
+ __setRerankTransportForTests(async (_url, init) => {
+ sent.push({ kind: 'rerank', auth: new Headers(init.headers).get('authorization') });
+ return new Response(JSON.stringify({ data: [{ index: 0, relevance_score: 0.9 }] }), { status: 200 });
+ });
+}
+
+afterEach(() => {
+ sent.length = 0;
+ __setEmbedTransportForTests(null);
+ __setGenerateTextTransportForTests(null);
+ __setGenerateObjectTransportForTests(null);
+ __setRerankTransportForTests(null);
+ resetGateway();
+});
+
+/** Keys an embedded engine or an unscoped call must never use: the environment canary and the process gateway's key. */
+const CANARY = key('canary');
+const PROCESS_KEY = key('process');
+const canaryEnv = { OPENAI_API_KEY: CANARY, ANTHROPIC_API_KEY: CANARY, VOYAGE_API_KEY: CANARY };
+function configureConflictingProcessGateway(): void {
+ configureGateway({ embedding_model: EMBEDDING.model, embedding_dimensions: EMBEDDING.dimensions, chat_model: 'openai:gpt-5.6', expansion_model: 'openai:gpt-5.6',
+ reranker_model: 'voyage:rerank-3-lite', env: { OPENAI_API_KEY: PROCESS_KEY, ANTHROPIC_API_KEY: PROCESS_KEY, VOYAGE_API_KEY: PROCESS_KEY } });
+}
+/** Every AI touchpoint once: embed, query embed, chat, expansion, rerank. */
+const everyCall = (label: string) => [
+ () => embed([`document ${label}`]),
+ () => embedQuery(`query ${label}`),
+ () => chat({ messages: [{ role: 'user', content: `hello ${label}` }] }),
+ () => expand(`expand ${label}`),
+ () => rerank({ query: `rerank ${label}`, documents: ['one'], model: 'voyage:rerank-3-lite' }),
+];
+const codes = async (calls: Array<() => unknown>) => Promise.all(calls.map(async call => (await failure(call))?.code ?? 'ok'));
+const REQUIRED = Array(5).fill('engine_scope_required');
+const detached = <T>(schedule: (run: () => void) => void, work: () => Promise<T>): Promise<T> =>
+ new Promise((resolve, reject) => schedule(() => { work().then(resolve, reject); }));
+
+describe('a mixed process: a local CLI engine and two embedded engines', () => {
+ test('unscoped, detached and post-close calls refuse engine_scope_required; scoped calls use their own keys; no call carries the canary', async () => {
+ installStubs();
+ configureConflictingProcessGateway();
+ await withEnv(canaryEnv, async () => {
+ const cli = await createEngine({ engine: 'pglite' });
+ const keyA = key('a');
+ const keyB = key('b');
+ const a = await openEngine(settingsFor(keyA));
+ const b = await openEngine(settingsFor(keyB));
+ let aOpen = true;
+ try {
+ const direct = await codes(everyCall('direct'));
+ expect(direct).toEqual(REQUIRED);
+ const error = await failure(() => chat({ messages: [{ role: 'user', content: 'hello' }] }));
+ expect(`${error!.message} ${error!.suggestion}`).toContain('withEngineScope');
+ expect(resolveAnthropicKey()).toBeUndefined();
+ expect((await failure(() => anthropicClientOptions()))?.code).toBe('engine_scope_required');
+
+ expect(await detached(run => setTimeout(run, 5), () => codes(everyCall('timer')))).toEqual(REQUIRED);
+ expect(await detached(queueMicrotask, () => codes(everyCall('microtask')))).toEqual(REQUIRED);
+ expect(await detached(run => setImmediate(run), () => codes(everyCall('immediate')))).toEqual(REQUIRED);
+ expect(sent).toEqual([]);
+
+ expect(await withEngineScope(a, () => detached(run => setTimeout(run, 5), () => codes(everyCall('a timer'))))).toEqual(Array(5).fill('ok'));
+ expect(await withEngineScope(b, () => codes(everyCall('b')))).toEqual(Array(5).fill('ok'));
+ const scopedAuth = sent.splice(0).map(s => s.auth);
+ expect(new Set(scopedAuth)).toEqual(new Set([`Bearer ${keyA}`, `Bearer ${keyB}`]));
+
+ expect(await withLocalScope(() => codes(everyCall('local')))).toEqual(Array(5).fill('ok'));
+ expect(await withEngineScope(cli, () => codes(everyCall('cli engine')))).toEqual(Array(5).fill('ok'));
+ expect(new Set(sent.splice(0).map(s => s.auth))).toEqual(new Set([`Bearer ${PROCESS_KEY}`]));
+ expect(withLocalScope(() => resolveAnthropicKey())).toBe(process.env.ANTHROPIC_API_KEY);
+
+ const afterClose = withEngineScope(a, () => detached(run => setTimeout(run, 200), () => codes(everyCall('a after close'))));
+ const unscopedAfterClose = detached(run => setTimeout(run, 200), () => codes(everyCall('unscoped after close')));
+ await a.disconnect();
+ aOpen = false;
+ const closedExpansionUnavailable = ['engine_scope_missing', 'engine_scope_missing', 'engine_scope_missing', 'ok', 'engine_scope_missing'];
+ expect(await afterClose).toEqual(closedExpansionUnavailable);
+ expect(await unscopedAfterClose).toEqual(REQUIRED);
+ expect(sent).toEqual([]);
+ } finally {
+ await Promise.all([aOpen ? a.disconnect() : null, b.disconnect(), cli.disconnect()]);
+ }
+ });
+ expect(sent.some(s => s.auth?.includes(CANARY))).toBe(false);
+ }, 120_000);
+
+ test('configureGatewayIfUninitialized is a no-op unscoped while an embedded engine is open, and configures in a local scope', async () => {
+ const home = mkdtempSync(join(tmpdir(), 'gbrain-scope-required-'));
+ mkdirSync(join(home, '.gbrain'));
+ writeFileSync(join(home, '.gbrain', 'config.json'), JSON.stringify({ engine: 'pglite', database_path: join(home, 'brain.pglite'), openai_api_key: CANARY }));
+ __unconfigureGatewayForTests();
+ await withEnv({ ...canaryEnv, GBRAIN_HOME: home }, async () => {
+ const engine = await openEngine(settingsFor(key('a')));
+ try {
+ configureGatewayIfUninitialized();
+ expect((await failure(() => withLocalScope(() => requireConfig())))?.message).toContain('not configured');
+ withLocalScope(() => configureGatewayIfUninitialized());
+ expect(withLocalScope(() => requireConfig()).env?.OPENAI_API_KEY).toBe(CANARY);
+ expect((await failure(() => requireConfig()))?.code).toBe('engine_scope_required');
+ } finally {
+ await engine.disconnect();
+ }
+ });
+ }, 60_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();
+ configureConflictingProcessGateway();
+ expect(await codes(everyCall('before'))).toEqual(Array(5).fill('ok'));
+ const engine: BrainEngine = await openEngine(settingsFor(key('a')));
+ expect(await codes(everyCall('while open'))).toEqual(REQUIRED);
+ await engine.disconnect();
+ sent.length = 0;
+ expect(await codes(everyCall('after'))).toEqual(Array(5).fill('ok'));
+ expect(new Set(sent.map(s => s.auth))).toEqual(new Set([`Bearer ${PROCESS_KEY}`]));
+ }, 60_000);
+});