Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Remote think runs the host think model unless think.remote_models allows the requested one (GBRA-437)

garrytan109de5aa5545
diff --git a/docs/guides/remote-mcp.md b/docs/guides/remote-mcp.md
index 13f6223618..11acdb1cdd 100644
--- a/docs/guides/remote-mcp.md
+++ b/docs/guides/remote-mcp.md
@@ -515,6 +515,12 @@ dedupe off) in the serve wrapper's environment.
client on the host when it should stop. Self-service registration stays
off unless you pass `--enable-dcr`, and even then every new connection waits
for your approval in the admin dashboard.
+- **Remote `think` runs your think model.** Every `think` answer is a paid
+ call on the host's key, so a connected client's `model` is used only when it
+ is your think model (`models.think`) or you allow it with
+ `gbrain config set think.remote_models <model>,<model>`. Any other model
+ answers on your think model, with a `model_override_ignored` notice instead
+ of an error.
- **Loopback bind.** The server keeps `127.0.0.1`; never pass
`--bind 0.0.0.0` for this shape. Tailscale is the only way in.
- **No secrets in chat or config.** The admin token lives in a 0600 file the
diff --git a/llms-full.txt b/llms-full.txt
index b8356e3356..4829e10a93 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -528,6 +528,12 @@ dedupe off) in the serve wrapper's environment.
client on the host when it should stop. Self-service registration stays
off unless you pass `--enable-dcr`, and even then every new connection waits
for your approval in the admin dashboard.
+- **Remote `think` runs your think model.** Every `think` answer is a paid
+ call on the host's key, so a connected client's `model` is used only when it
+ is your think model (`models.think`) or you allow it with
+ `gbrain config set think.remote_models <model>,<model>`. Any other model
+ answers on your think model, with a `model_override_ignored` notice instead
+ of an error.
- **Loopback bind.** The server keeps `127.0.0.1`; never pass
`--bind 0.0.0.0` for this shape. Tailscale is the only way in.
- **No secrets in chat or config.** The admin token lives in a 0600 file the
diff --git a/scripts/serial-files.tsv b/scripts/serial-files.tsv
index 610c3b4587..b66f01231a 100644
--- a/scripts/serial-files.tsv
+++ b/scripts/serial-files.tsv
@@ -413,6 +413,7 @@ test/sync-soft-delete.serial.test.ts R1 R1: mutates process.env (GBRAIN_HOME)
test/takes-vector-lifecycle-5885.serial.test.ts global-state global-state: process-wide test seams __setEmbedTransportForTests; configureGateway changes the process-wide AI gateway
test/thin-client-write-errors.serial.test.ts global-state global-state: binds local servers/ports
test/think-cli-source-flag.serial.test.ts R2 R2: mock.module(../src/core/think/index.ts, ../src/core/config.ts, ../src/core/source-resolver.ts) replaces modules for every file in the process
+test/think-remote-model-thin-client.serial.test.ts R2 R2: mock.module(../src/core/config.ts, ../src/core/mcp-client.ts) replaces modules for every file in the process
test/think-embed-question-wiring.serial.test.ts R2 R2: mock.module(../src/core/embedding.ts, ../src/core/think/index.ts) replaces modules for every file in the process
test/think-extractive.serial.test.ts global-state global-state: process-wide test seams __setChatTransportForTests, __setEmbedTransportForTests, __setUsageLogPathForTests
test/think-gather-adaptive-return.serial.test.ts R2 R2: mock.module(../src/core/embedding.ts) replaces modules for every file in the process
diff --git a/src/commands/think.ts b/src/commands/think.ts
index 2365523000..63e775394e 100644
--- a/src/commands/think.ts
+++ b/src/commands/think.ts
@@ -11,7 +11,7 @@ import { loadConfig, isThinClient } from '../core/config.ts';
import { callRemoteTool, unpackToolResult } from '../core/mcp-client.ts';
import { canonicalLookup } from '../core/model-pricing.ts';
import { embedQueryWithPrefix } from '../core/search/query-prefix.ts';
-import { keylessThinkNotice } from '../core/interop-notices.ts';
+import { keylessThinkNotice, modelOverrideIgnoredNotice } from '../core/interop-notices.ts';
import { applyCliOpNotices, captureOpNotice } from '../cli/op-notices.ts';
function flagValue(args: string[], name: string): string | undefined {
@@ -57,7 +57,9 @@ Options:
--model <name> Override the model: provider:model (preferred) or
provider/model or a bare alias. An explicit --model that
can't be resolved is a hard error (exit 1) — never a
- silent no-LLM degrade.
+ silent no-LLM degrade. On a thin client the remote
+ brain answers with its own think model unless its
+ host allows this one (think.remote_models).
--source <id> Scope evidence gathering to this source. An unknown
or archived source is a hard error (exit 1).
--since YYYY-MM-DD Start of temporal window
@@ -263,6 +265,8 @@ prints what would have been the input (exit 0).
// F8: keyless-by-design output carries its explanation as an info notice.
if (result.synthesis_status === 'no_llm') captureOpNotice(keylessThinkNotice());
+ const ignoredModel = /^MODEL_OVERRIDE_IGNORED:(not_allowed|unusable)$/.exec((result.warnings as string[] | undefined)?.find(w => w.startsWith('MODEL_OVERRIDE_IGNORED:')) ?? '');
+ if (ignoredModel) captureOpNotice(modelOverrideIgnoredNotice(ignoredModel[1] as 'not_allowed' | 'unusable'));
const { persist_base: _persistBase, ...visible } = result;
const { result: jsonDoc, stderr: noticeText } = applyCliOpNotices({
...visible,
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 9368f567d1..4ddd51b2a6 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1494,6 +1494,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.622.0', id: 'purge_cancels_deferred_write_gst1602', text: 'With `persistence.refresh_barrier` on, `gbrain forget <id> --purge` no longer refuses `purge_blocked_pending_recovery` while a write deferred behind a refresh holds the claim in its staged body: the deferred write was never claimed, so the purge cancels it with `purged_content`, as it does a queued one, and removes the content at once instead of up to 15 minutes later.' },
{ since: '0.60.623.0', id: 'owner_reads_private_gst2059', text: 'A brain can now name its owner: `gbrain access owner set <member>` (config `access.owner_member`, an enabled member). Every remote credential or stdio server bound to that member reads the whole brain, `visibility: private` pages, privacy-alias pages (`access: private`, ...), derived and pinned-question pages included, through `get_page`, `search`, `query`, `recall` and the other page reads in the sources its grant reads, and `recall` returns its private facts. `readable_by` and folder rules still bind it, and it is not relaxed when it speaks for a shared-room audience. A page the owner\'s credential creates in `default` through `put_page` is not kept to the owner (no `readable_by: [member:<id>]`). Other members, unbound and public callers are unchanged. `_meta.access.relaxation` reads `owner` for such a call, and `gbrain access check --token <name>` reports it. `gbrain repair private-labels` (named runs only) previews the `access: private` labels stamped on ordinary pages with counts per category, keeps real restrictions, and clears the rest in reviewed batches (`--apply --expect <hash>`), recording each change so `--class restore` can put it back. The bulk-ingestion page template no longer writes an `access:` line; what each designation means is in docs/guides/access-designations.md.' },
{ since: '0.60.626.0', id: 'record_origin_checkout_lockdown_8888', text: '`gbrain sources record-origin <id>... --remote --apply` now also turns git-lfs downloads and hooks off in each recorded source\'s existing checkout (its `.git/config`: `lfs.fetchexclude=*`, `core.hooksPath=/dev/null`, `lfs.locksverify=false`), not only on later reclones, in the repository\'s shared config, and refuses `write_failed` naming the key when a worktree-scoped or included setting still overrides one; a source already recorded as remote gets the lock-down on the next `--remote --apply` when its checkout lacks it, even when its files now use git-lfs, and a key that holds several values in that config is replaced by the one clone-time value. On a managed brain it takes the same worktree locks a reclone takes, refusing the id `source_busy` while a reclone, refresh or write holds them, and a reclone reads the record under its own locks. A write that fails is reported for its own id (`write_failed`) instead of ending the run. The git-lfs check reads a committed `.gitattributes` under a directory whose name holds a tab, ignores commented-out `filter=lfs` lines, says when a committed rule only declares an LFS filter, records a clone of an empty repository instead of refusing it, and names the cause of an `lfs_unknown` refusal.' },
+ { since: '0.60.626.0', id: 'remote_think_host_model_gbra437', text: 'A remote `think` (MCP, HTTP or a thin client) now runs on the brain host\'s think model (`models.think`, then `models.default`) unless the host lists the requested `model` in the new `think.remote_models` key (comma-separated, empty by default). An unlisted model, or a listed one the host cannot run, no longer fails the call with the explicit-model error: the host model answers, `warnings` carries `MODEL_OVERRIDE_IGNORED:not_allowed` or `:unusable`, and the result carries a `model_override_ignored` notice. Remote `rounds` runs one round. The local CLI `--model` is unchanged, and a keyless brain answers as before.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/src/core/config-runtime-keys.ts b/src/core/config-runtime-keys.ts
index 1e31097331..8c5a4c94a2 100644
--- a/src/core/config-runtime-keys.ts
+++ b/src/core/config-runtime-keys.ts
@@ -11,6 +11,7 @@ export const RUNTIME_READER_CONFIG_KEYS: readonly string[] = [
'embed.content_drift.pass_interval_hours', // content-drift-sweep.ts: hours between completed content-drift passes, default 24 (0 = every run)
'facts.absorb_warn_threshold', // doctor facts_extraction_health absorb-refusal warn threshold, default 10 per 24 h
'think.trajectory_enabled', // think/index.ts: trajectory substrate on temporal intents, default on
+ 'think.remote_models', // ops/takes.ts (GBRA-437): comma-separated models a remote think may pick; default empty, so remote callers get the host think model
'embedding_image_ocr_max_images', 'embedding_image_ocr_max_usd', // import-file.ts image-OCR per-run caps, default 200 images / $1
'agent.search_snippet_chars', // ops/search.ts subagent snippet cap, default 300 (0 = full text)
'skillopt.allowed_skills', // JSON array of skills remote callers may optimize (ops/skillopt.ts, shared-skills/optimizer.ts); default deny-all
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index af6d21fed8..95868630ae 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -985,6 +985,7 @@ export const NOTICE_CODES = {
local_transcripts: { kind: 'info', summary: 'The brain host keeps recent session transcripts that page reads never return and this connection cannot read; the fix is the CLI read (`gbrain transcripts recent --json`).' },
synthesis_keyless: { kind: 'info', summary: 'think returned gathered evidence without synthesis because no chat-model key is configured (by design on a keyless brain).' },
think_not_saved: { kind: 'info', summary: 'think save/take persist only for the local CLI, so this answer was not saved.' },
+ model_override_ignored: { kind: 'info', summary: 'A remote think named a model the brain host does not allow for remote callers (think.remote_models) or cannot run, so the host think model answered instead.' },
onboard_opportunities: { kind: 'coaching', summary: 'Onboarding checks found work that would improve this brain (gbrain onboard --check lists it).' },
onboard_stale_chunks: { kind: 'coaching', summary: 'This search could not match chunks that have no embedding; the remedy is an embedding backfill (paid, ask first).' },
onboard_link_coverage: { kind: 'coaching', summary: 'Few people/company pages have incoming links, so backlinks and graph answers are thin; the remedy is link extraction.' },
diff --git a/src/core/interop-notices.ts b/src/core/interop-notices.ts
index 8eea56464c..9d3916f029 100644
--- a/src/core/interop-notices.ts
+++ b/src/core/interop-notices.ts
@@ -296,6 +296,30 @@ export function keylessThinkNotice(): Notice {
};
}
+/** GBRA-437: a remote think's `model` was not used; the host's think model answered instead. */
+export function modelOverrideIgnoredNotice(reason: 'not_allowed' | 'unusable'): Notice {
+ return {
+ code: 'model_override_ignored',
+ kind: 'info',
+ dedupe_key: reason,
+ why: reason === 'not_allowed'
+ ? 'This brain runs think on its own configured model for remote callers, so the requested model was not used; the answer came from the host think model (modelUsed names it). Omit model, or ask the brain owner to allow it on the brain host.'
+ : 'The requested model is allowed for remote callers on this brain but cannot run there right now, so the host think model answered instead (modelUsed names it).',
+ ...(reason === 'not_allowed' ? {
+ fix: {
+ argv: ['gbrain', 'config', 'set', 'think.remote_models', '<models>'],
+ consent: ['paid'],
+ actor: 'host_admin',
+ why: 'think.remote_models is a comma-separated list of models remote callers may pick for think; every think answer is a paid call on the host\'s key.',
+ user_message: 'This brain answers remote think calls with its own configured model. The owner can allow another model on the brain host with gbrain config set think.remote_models <models>.',
+ inputs: [{ name: 'models', how: 'The current think.remote_models value plus the requested model, comma-separated.' }],
+ verify: { argv: ['gbrain', 'config', 'get', 'think.remote_models'] },
+ requires_exclusive: false,
+ },
+ } : {}),
+ };
+}
+
/** think with save/take over MCP: persistence is local-CLI only, so `saved_slug` is null. */
export function thinkNotSavedNotice(): Notice {
return {
diff --git a/src/core/operation-manifest.generated.ts b/src/core/operation-manifest.generated.ts
index 4f3cba05e1..392f8a96f5 100644
--- a/src/core/operation-manifest.generated.ts
+++ b/src/core/operation-manifest.generated.ts
@@ -4526,7 +4526,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [
},
"model": {
"type": "string",
- "description": "Model override (alias or full id). Falls through models.think → models.default → GBRAIN_MODEL → opus."
+ "description": "Model override (alias or full id). Falls through models.think → models.default → GBRAIN_MODEL → opus. Remote callers get the host think model unless the host lists this one in think.remote_models."
},
"since": {
"type": "string",
diff --git a/src/core/ops/takes.ts b/src/core/ops/takes.ts
index 375b38d2d6..3fcbe20fbf 100644
--- a/src/core/ops/takes.ts
+++ b/src/core/ops/takes.ts
@@ -296,6 +296,25 @@ function thinkModelError(ctx: OperationContext, e: unknown): unknown {
`Nothing was synthesized. Omit ${name} to use the configured think model (models.think, then models.default), or pass a model id this brain can reach.`);
}
+export const THINK_REMOTE_MODELS_KEY = 'think.remote_models';
+
+/**
+ * GBRA-437: a remote caller's think model. The host's own think model and any model the host
+ * lists in think.remote_models run; anything else runs the host model and reports why.
+ */
+async function remoteThinkModel(engine: OperationContext['engine'], requested: string | undefined): Promise<{ model?: string; ignored?: 'not_allowed' | 'unusable' }> {
+ if (!requested) return {};
+ const [{ resolveModel }, { normalizeModelId }, { probeChatModel }] = await Promise.all([
+ import('../model-config.ts'), import('../model-id.ts'), import('../ai/gateway.ts'),
+ ]);
+ const resolve = async (cliFlag?: string) => normalizeModelId(await resolveModel(engine, { cliFlag, configKey: 'models.think', tier: 'deep', fallback: 'opus' }));
+ const [wanted, host, listed] = await Promise.all([resolve(requested), resolve(), engine.getConfig(THINK_REMOTE_MODELS_KEY)]);
+ if (wanted === host) return {};
+ const allowed = await Promise.all((listed ?? '').split(',').map(m => m.trim()).filter(Boolean).map(m => resolve(m)));
+ if (!allowed.includes(wanted)) return { ignored: 'not_allowed' };
+ return probeChatModel(wanted).ok ? { model: wanted } : { ignored: 'unusable' };
+}
+
const think: Operation = {
name: 'think',
idempotent: false,
@@ -308,7 +327,7 @@ const think: Operation = {
rounds: { type: 'number', description: 'Multi-pass: 1 (default). Round-loop scaffolding is in place; gap-driven retrieval ships in v0.29.' },
save: { type: 'boolean', description: 'Persist a synthesis page (local-CLI only; ignored for MCP)' },
take: { type: 'boolean', description: 'Append a take row to the anchor page (requires anchor)' },
- model: { type: 'string', description: 'Model override (alias or full id). Falls through models.think → models.default → GBRAIN_MODEL → opus.' },
+ model: { type: 'string', description: 'Model override (alias or full id). Falls through models.think → models.default → GBRAIN_MODEL → opus. Remote callers get the host think model unless the host lists this one in think.remote_models.' },
since: { type: 'string', description: 'Start of temporal window (YYYY-MM-DD or YYYY-MM). Omit both bounds and a question naming one explicit date (2026-09-15, 2026-09, September 2026) is bounded to it; the result says window_source.' },
until: { type: 'string', description: 'End of temporal window' },
reference_date: { type: 'string', description: 'YYYY-MM-DD the question\'s relative time words resolve against (default: today in brain.timezone).' },
@@ -327,21 +346,21 @@ const think: Operation = {
// forwards to findTrajectory. CLI callers don't go through this op
// and get default scope + remote=false from runThink's CLI path.
const thinkScope = thinkSourceScopeOpts(ctx);
+ const requestedModel = p.model ? String(p.model) : undefined;
+ const thinkModel = remote ? await remoteThinkModel(ctx.engine, requestedModel) : { model: requestedModel };
const { runThink, persistSynthesis } = await import('../think/index.ts');
const result = await runThink(ctx.engine, {
question: String(p.question),
// #3734: MCP think must populate the question vector for takes retrieval.
embedQuestion: (q) => embedQueryWithPrefix(ctx.engine, q),
anchor: p.anchor ? String(p.anchor) : undefined,
- rounds: typeof p.rounds === 'number' ? (p.rounds as number) : undefined,
+ rounds: remote ? 1 : typeof p.rounds === 'number' ? (p.rounds as number) : undefined,
save: safeSave,
take: safeTake,
- model: p.model ? String(p.model) : undefined,
- // #1698 (C3): a remote caller that explicitly supplies a model gets the same
- // hard-error-on-unresolvable behavior as the CLI (loud op error envelope),
- // instead of silently degrading to a no-LLM stub answer. No model param →
- // false → configured/default model keeps its graceful path.
- modelExplicit: !!p.model,
+ model: thinkModel.model,
+ // #1698: the local CLI hard-errors on an unusable explicit model. A remote
+ // model is already resolved against the host's allow-list above, so it never errors.
+ modelExplicit: !remote && !!requestedModel,
since: p.since ? String(p.since) : undefined,
until: p.until ? String(p.until) : undefined,
...(typeof p.reference_date === 'string' ? { referenceDate: p.reference_date } : {}),
@@ -398,8 +417,12 @@ const think: Operation = {
}
// F8: the explanations the CLI formatter prints, as model-visible notices.
- const { keylessThinkNotice, thinkNotSavedNotice } = await import('../interop-notices.ts');
+ const { keylessThinkNotice, thinkNotSavedNotice, modelOverrideIgnoredNotice } = await import('../interop-notices.ts');
if (result.synthesis_status === 'no_llm') ctx.emitNotice?.(keylessThinkNotice());
+ if (thinkModel.ignored && result.synthesis_status !== 'no_llm') {
+ result.warnings.push(`MODEL_OVERRIDE_IGNORED:${thinkModel.ignored}`);
+ ctx.emitNotice?.(modelOverrideIgnoredNotice(thinkModel.ignored));
+ }
if (remote && (Boolean(p.save) || Boolean(p.take))) ctx.emitNotice?.(thinkNotSavedNotice());
const { recordThinkAnswer, feedbackMetaFields } = await import('../feedback/record.ts');
const feedbackMeta = feedbackMetaFields(await recordThinkAnswer(ctx, 'think', result));
diff --git a/test/config-reader-keys-registered.test.ts b/test/config-reader-keys-registered.test.ts
index e252fcddb7..87acb971cd 100644
--- a/test/config-reader-keys-registered.test.ts
+++ b/test/config-reader-keys-registered.test.ts
@@ -18,6 +18,7 @@ import { ENTRY_BUDGET_KEY } from '../src/commands/doctor/budget.ts';
import { ORPHAN_FULL_SCAN_KEY } from '../src/commands/doctor/checks/orphan-estimate.ts';
import { PAGE_EMBED_CAP_KEY } from '../src/core/page-embedding-budget.ts';
import { ENTITY_IDENTITY_UNION_CONFIG_KEY } from '../src/core/entity-identity.ts';
+import { THINK_REMOTE_MODELS_KEY } from '../src/core/ops/takes.ts';
import { scanConfigReads, type ConfigRead } from './helpers/config-reader-scan.ts';
import {
ENUMERATED_TEMPLATE_PREFIXES,
@@ -39,6 +40,7 @@ describe('#6780 runtime config keys are registered', () => {
['doctor.orphan_ratio.full_scan_max_pages', ORPHAN_FULL_SCAN_KEY],
['embed.max_usd_per_page', PAGE_EMBED_CAP_KEY],
['entity_identity.union', ENTITY_IDENTITY_UNION_CONFIG_KEY],
+ ['think.remote_models', THINK_REMOTE_MODELS_KEY],
])('%s (the reader constant) is in KNOWN_CONFIG_KEYS', (name, constant) => {
expect(constant).toBe(name);
expect(KNOWN_CONFIG_KEYS).toContain(constant);
diff --git a/test/fixtures/goldens/cli/tools-json.json b/test/fixtures/goldens/cli/tools-json.json
index c742bbcd5b..a495d5ab43 100644
--- a/test/fixtures/goldens/cli/tools-json.json
+++ b/test/fixtures/goldens/cli/tools-json.json
@@ -2,8 +2,8 @@
"golden": {
"exitCode": 0,
"stderr": "",
- "stdoutBytes": 282967,
- "stdoutSha256": "73f135de04ba7cceced4d9fd952b23aaefd7fb4cad5ebdf3dce1aca953c70f84",
+ "stdoutBytes": 283062,
+ "stdoutSha256": "af67ca2411680ead817ea10538a37e5c3e71c10d54fb03c483ee966a9d1b7f54",
"toolNames": [
"remember",
"entity",
@@ -5286,7 +5286,7 @@
"type": "string"
},
"model": {
- "description": "Model override (alias or full id). Falls through models.think → models.default → GBRAIN_MODEL → opus.",
+ "description": "Model override (alias or full id). Falls through models.think → models.default → GBRAIN_MODEL → opus. Remote callers get the host think model unless the host lists this one in think.remote_models.",
"type": "string"
},
"question": {
diff --git a/test/mcp-notice-channels.test.ts b/test/mcp-notice-channels.test.ts
index 3903978ed9..f8a269f4de 100644
--- a/test/mcp-notice-channels.test.ts
+++ b/test/mcp-notice-channels.test.ts
@@ -48,7 +48,7 @@ describe('DEGRADED_STAGE_GUIDANCE', () => {
test('every Lane F notice code is registered with its kind', () => {
expect(NOTICE_CODES.degraded_recall.kind).toBe('degraded');
- for (const c of ['source_binding_narrowed', 'degraded_dedup', 'synthesis_keyless', 'think_not_saved', 'listing_truncated'] as const) {
+ for (const c of ['source_binding_narrowed', 'degraded_dedup', 'synthesis_keyless', 'think_not_saved', 'model_override_ignored', 'listing_truncated'] as const) {
expect(NOTICE_CODES[c].kind).toBe('info');
}
});
diff --git a/test/think-pipeline.test.ts b/test/think-pipeline.test.ts
index b94d9b6eb2..6535a42153 100644
--- a/test/think-pipeline.test.ts
+++ b/test/think-pipeline.test.ts
@@ -689,14 +689,20 @@ describe('think MCP op — #1698 C3 + #10', () => {
logger: { info() {}, warn() {}, error() {}, debug() {} } as any,
});
- test('C3: remote caller with explicit bad model → op throws (modelExplicit wired)', async () => {
+ test('C3: local caller with explicit bad model → op throws (modelExplicit wired)', async () => {
const op = operationsByName['think'];
expect(op).toBeDefined();
await expect(
- op.handler(baseCtx(true) as any, { question: 'q', model: 'bogusprovider:foo' }),
+ op.handler(baseCtx(false) as any, { question: 'q', model: 'bogusprovider:foo' }),
).rejects.toThrow(/not usable.*unknown_provider/);
});
+ test('GBRA-437: remote caller with a model the host does not allow → host model, never a throw', async () => {
+ const op = operationsByName['think'];
+ const res: any = await withoutAnthropicKey(() => op.handler(baseCtx(true) as any, { question: 'q', model: 'bogusprovider:foo' }));
+ expect(res.warnings.some((w: string) => w.startsWith('MODEL_NOT_USABLE'))).toBe(false);
+ });
+
test('#10: local save with no synthesis → saved_slug is null, not "" + warning surfaced', async () => {
const op = operationsByName['think'];
// Hermetic no-key: synthesisOk=false → persistSynthesis returns
diff --git a/test/think-remote-model-thin-client.serial.test.ts b/test/think-remote-model-thin-client.serial.test.ts
new file mode 100644
index 0000000000..faf6c9c89b
--- /dev/null
+++ b/test/think-remote-model-thin-client.serial.test.ts
@@ -0,0 +1,69 @@
+/**
+ * GBRA-437 PR 1: the thin client's `gbrain think --model` shows why the brain host ignored the model.
+ *
+ * 1. Protects: a thin-client think whose model the remote brain does not allow prints the
+ * model_override_ignored notice (in --json, under `notices`), with the host model's answer.
+ * 2. Fails when: the thin client drops the server's MODEL_OVERRIDE_IGNORED warning silently.
+ * 3. Existing coverage: test/think-remote-model.test.ts pins the server side on both engines.
+ * 4. Real seams: the real think op through MCP dispatch (remote=true) on PGLite stands in for the
+ * remote server; callRemoteTool and isThinClient are mocked so the CLI takes its thin-client branch.
+ */
+import { afterAll, beforeAll, describe, expect, mock, test } from 'bun:test';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { configureGateway, resetGateway, __setGenerateTextTransportForTests } from '../src/core/ai/gateway.ts';
+import { dispatchToolCall } from '../src/mcp/dispatch.ts';
+
+const engine = new PGLiteEngine();
+
+const realConfig = await import('../src/core/config.ts');
+mock.module('../src/core/config.ts', () => ({ ...realConfig, loadConfig: () => ({ engine: 'pglite' }), isThinClient: () => true }));
+const realClient = await import('../src/core/mcp-client.ts');
+mock.module('../src/core/mcp-client.ts', () => ({
+ ...realClient,
+ callRemoteTool: async (_cfg: unknown, tool: string, params: Record<string, unknown>) =>
+ dispatchToolCall(engine, tool, Object.fromEntries(Object.entries(params).filter(([, v]) => v !== undefined)), { remote: true, transport: 'http', sourceId: 'default', sessionId: 'thin-client-server' }),
+}));
+
+const { runThinkCli } = await import('../src/commands/think.ts');
+
+class ExitSentinel extends Error { constructor(readonly code: number) { super('exit ' + code); } }
+
+async function runCli(args: string[]) {
+ const out: string[] = [];
+ const savedLog = console.log, savedError = console.error, savedExit = process.exit;
+ console.log = (...a: unknown[]) => { out.push(a.map(String).join(' ')); };
+ console.error = () => {};
+ (process as unknown as { exit: (c?: number) => never }).exit = ((c?: number) => { throw new ExitSentinel(c ?? 0); }) as never;
+ try { await runThinkCli(null as never, args); return { code: 0, out }; }
+ catch (e) { if (e instanceof ExitSentinel) return { code: e.code, out }; throw e; }
+ finally { console.log = savedLog; console.error = savedError; (process as unknown as { exit: typeof savedExit }).exit = savedExit; }
+}
+
+describe('thin-client think --model', () => {
+ beforeAll(async () => {
+ await engine.connect({});
+ await engine.initSchema();
+ await engine.setConfig('models.think', 'openai:gpt-6.1-sol');
+ configureGateway({ chat_model: 'openai:gpt-6.1-sol', env: { OPENAI_API_KEY: 'fake-openai' } });
+ __setGenerateTextTransportForTests((async (args: { model: { modelId: string } }) => ({
+ content: [{ type: 'text', text: JSON.stringify({ answer: 'answered by ' + args.model.modelId, citations: [], gaps: [] }) }],
+ finishReason: 'stop', usage: { inputTokens: 3, outputTokens: 2 },
+ })) as never);
+ }, 120_000);
+ afterAll(async () => { __setGenerateTextTransportForTests(null); resetGateway(); await engine.disconnect(); });
+
+ test('a model the host does not allow answers on the host model and the CLI shows model_override_ignored', async () => {
+ const r = await runCli(['who', 'founded', 'acme-example', '--model', 'openai:gpt-5.5', '--json']);
+ expect(r.code).toBe(0);
+ const doc = JSON.parse(r.out.join('\n'));
+ expect(doc.modelUsed).toBe('openai:gpt-6.1-sol');
+ expect(doc.warnings).toContain('MODEL_OVERRIDE_IGNORED:not_allowed');
+ expect(JSON.stringify(doc.notices ?? [])).toContain('model_override_ignored');
+ });
+
+ test('without --model the CLI shows no model_override_ignored notice', async () => {
+ const r = await runCli(['who', 'founded', 'acme-example', '--json']);
+ expect(r.code).toBe(0);
+ expect(JSON.stringify(JSON.parse(r.out.join('\n')).notices ?? [])).not.toContain('model_override_ignored');
+ });
+});
diff --git a/test/think-remote-model.test.ts b/test/think-remote-model.test.ts
new file mode 100644
index 0000000000..22b8b6b831
--- /dev/null
+++ b/test/think-remote-model.test.ts
@@ -0,0 +1,134 @@
+/**
+ * GBRA-437 PR 1: a remote think runs the brain host's think model.
+ *
+ * 1. Protects: a remote caller's `model` runs only when it is the host's own think model or the host lists it in
+ * think.remote_models; anything else (including a listed model the host cannot run) answers on the host think
+ * model with a model_override_ignored notice, never an error. Remote `rounds` runs one round. The local
+ * operation keeps #1698: an explicit model runs as named and an unusable one throws. A keyless brain answers
+ * remote think the same way with or without `model`.
+ * 2. Fails when: a remote caller picks an unlisted (pricier) model on the host's key, a remote model choice errors,
+ * the notice is missing or fires on a keyless brain, or the local path loses its explicit-model behavior.
+ * 3. Existing coverage: test/think-pipeline.test.ts pins runThink's #1698 explicit-model error.
+ * 4. Real seams: MCP dispatch with remote=true on a repo-less brain, the real gateway with a stub chat transport.
+ */
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { randomUUID } from 'node:crypto';
+import type { BrainEngine } from '../src/core/engine.ts';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { configureGateway, resetGateway, __setGenerateTextTransportForTests } from '../src/core/ai/gateway.ts';
+import { dispatchToolCall } from '../src/mcp/dispatch.ts';
+import { operationsByName } from '../src/core/operations.ts';
+import { testBackends } from './helpers/test-backends.ts';
+import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
+import { withEnv } from './helpers/with-env.ts';
+
+const HOST = 'openai:gpt-6.1-sol';
+const OTHER = 'openai:gpt-5.5';
+const NO_KEYS = { OPENAI_API_KEY: undefined, ANTHROPIC_API_KEY: undefined, VOYAGE_API_KEY: undefined, GBRAIN_EMBEDDING_MODEL: undefined, GBRAIN_MODEL: undefined };
+
+for (const kind of testBackends()) {
+ describe('remote think runs the host think model (' + kind + ', repo-less)', () => {
+ let engine: BrainEngine;
+ let close: () => Promise<void>;
+ const called: string[] = [];
+
+ async function remoteThink(params: Record<string, unknown>) {
+ const out = await dispatchToolCall(engine, 'think', { question: 'who founded acme-example', ...params }, { remote: true, transport: 'http', sourceId: 'default', sessionId: randomUUID() });
+ const body = JSON.parse(out.content[0]!.text);
+ const notices = ((out._meta as { gbrain_notices?: Array<{ code: string; why: string }> } | undefined)?.gbrain_notices ?? []);
+ return { isError: out.isError === true, body, notices, codes: notices.map(n => n.code), first: out.content[0]!.text };
+ }
+
+ function keyed() {
+ configureGateway({ chat_model: HOST, env: { OPENAI_API_KEY: 'fake-openai' } });
+ __setGenerateTextTransportForTests((async (args: { model: { modelId: string } }) => {
+ called.push(args.model.modelId);
+ return { content: [{ type: 'text', text: JSON.stringify({ answer: 'answered by ' + args.model.modelId, citations: [], gaps: [] }) }], finishReason: 'stop', usage: { inputTokens: 3, outputTokens: 2 } };
+ }) as never);
+ }
+
+ beforeAll(async () => {
+ if (kind === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
+ else { engine = new PGLiteEngine(); await engine.connect({ engine: 'pglite' } as never); await engine.initSchema(); close = () => engine.disconnect(); }
+ await engine.setConfig('models.think', HOST);
+ }, 120_000);
+
+ afterEach(async () => {
+ __setGenerateTextTransportForTests(null);
+ resetGateway();
+ called.length = 0;
+ await engine.unsetConfig('think.remote_models');
+ });
+
+ afterAll(async () => { await close?.(); });
+
+ test('an unlisted remote model answers on the host model with a notice, not an error', async () => {
+ keyed();
+ const r = await remoteThink({ model: OTHER });
+ expect(r.isError).toBe(false);
+ expect(called).toEqual(['gpt-6.1-sol']);
+ expect(r.body.modelUsed).toBe(HOST);
+ expect(r.body.warnings).toContain('MODEL_OVERRIDE_IGNORED:not_allowed');
+ expect(r.codes).toContain('model_override_ignored');
+ });
+
+ test('a model the host lists in think.remote_models runs, with no notice', async () => {
+ keyed();
+ await engine.setConfig('think.remote_models', 'anthropic:claude-opus-5-5, ' + OTHER);
+ const r = await remoteThink({ model: OTHER });
+ expect(r.isError).toBe(false);
+ expect(called).toEqual(['gpt-5.5']);
+ expect(r.body.modelUsed).toBe(OTHER);
+ expect(r.codes).not.toContain('model_override_ignored');
+ });
+
+ test('a listed model the host cannot run answers on the host model with a notice, not an error', async () => {
+ keyed();
+ await engine.setConfig('think.remote_models', 'voyage:voyage-3');
+ const r = await remoteThink({ model: 'voyage:voyage-3' });
+ expect(r.isError).toBe(false);
+ expect(called).toEqual(['gpt-6.1-sol']);
+ expect(r.body.warnings).toContain('MODEL_OVERRIDE_IGNORED:unusable');
+ expect(r.notices.find(n => n.code === 'model_override_ignored')?.why).toContain('cannot run');
+ });
+
+ test('a model param naming the host think model runs it with no notice', async () => {
+ keyed();
+ const r = await remoteThink({ model: HOST });
+ expect(r.isError).toBe(false);
+ expect(called).toEqual(['gpt-6.1-sol']);
+ expect(r.codes).not.toContain('model_override_ignored');
+ expect(r.body.warnings.some((w: string) => w.startsWith('MODEL_OVERRIDE_IGNORED'))).toBe(false);
+ });
+
+ test('remote rounds runs one round', async () => {
+ keyed();
+ const r = await remoteThink({ rounds: 5 });
+ expect(r.body.rounds).toBe(1);
+ });
+
+ test('the local operation keeps #1698: an explicit model runs as named and an unusable one throws', async () => {
+ keyed();
+ const ctx = { engine, remote: false, sourceId: 'default', config: {} } as never;
+ const ran = await operationsByName.think.handler(ctx, { question: 'who founded acme-example', model: OTHER }) as { modelUsed: string; warnings: string[] };
+ expect(ran.modelUsed).toBe(OTHER);
+ expect(ran.warnings.some(w => w.startsWith('MODEL_OVERRIDE_IGNORED'))).toBe(false);
+ await expect(operationsByName.think.handler(ctx, { question: 'who founded acme-example', model: 'bogusprovider:foo' })).rejects.toThrow(/not usable|unknown_provider/);
+ });
+
+ test('a keyless brain gives the same no_llm answer with or without model', async () => {
+ await engine.unsetConfig('models.think');
+ await withEnv(NO_KEYS, async () => {
+ configureGateway({ env: {} });
+ const without = await remoteThink({});
+ const withModel = await remoteThink({ model: OTHER });
+ expect(without.body.synthesis_status).toBe('no_llm');
+ expect(withModel.isError).toBe(false);
+ expect(withModel.first).toBe(without.first);
+ expect(withModel.codes).toEqual(without.codes);
+ expect(withModel.codes).not.toContain('model_override_ignored');
+ });
+ await engine.setConfig('models.think', HOST);
+ });
+ });
+}