Compare commits

..
Author SHA1 Message Date
Garry TanandClaude Fable 5 2247540b4f fix(init,mcp): seed init AI options from env on cold install; whoami reports stdio transport
Two backlog fixes:

- init (#1058): loadConfig() returns null on a cold install (no config.json
  AND no DATABASE_URL), short-circuiting before its env merge — so
  GBRAIN_EMBEDDING_MODEL / GBRAIN_EMBEDDING_DIMENSIONS /
  GBRAIN_EXPANSION_MODEL / GBRAIN_CHAT_MODEL were silently ignored and
  Tier-3 detection auto-picked by API key instead. resolveAIOptions' config
  seed now falls back to those env vars directly when loadConfig() is null
  (new exported helper seedAIOptionsFromConfig, env-injectable for tests).

- whoami (#1061): the stdio MCP dispatch is remote/untrusted by design but
  has no per-token auth (local pipe), so whoami threw unknown_transport on
  the primary stdio surface. The stdio dispatch now marks
  ctx.transport = 'stdio' and whoami returns {transport: 'stdio', scopes: []}
  for it. Trust posture unchanged: remote stays true, the marker is never
  used for trust decisions, and an unmarked auth-less remote context still
  throws (fail-closed preserved).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-21 14:24:02 -07:00
17 changed files with 173 additions and 391 deletions
-59
View File
@@ -820,10 +820,6 @@ export async function doctorReportRemote(engine: BrainEngine): Promise<DoctorRep
// v0.42.x (#1794, 4A): pool-budget nudge when GBRAIN_MAX_CONNECTIONS is set.
checks.push(await checkPoolBudget(engine));
// #2552: warn when an explicit embed-concurrency override fans out against
// a local single-slot embedding endpoint (silent backfill starvation).
checks.push(await checkEmbedConcurrency());
// v0.42.7 (#1696): link-extraction lag. Strictly SQL (single indexed COUNT),
// safe on the thin-client/remote path — remote operators on checkout-less
// Postgres brains are exactly who can't otherwise see the extraction backlog.
@@ -3819,61 +3815,6 @@ export function computePoolBudgetCheck(
};
}
/**
* #2552: warn when an explicit GBRAIN_EMBED_CONCURRENCY override fans out
* against a local single-slot embedding endpoint (Ollama / llama-server /
* localhost base URL). Requests serialize on the one loaded model, so N
* parallel pages multiply latency xN and can exceed the fetch timeout with
* no surfaced error the backfill silently starves. (When the env var is
* unset, embed auto-caps at LOCAL_EMBED_CONCURRENCY_CAP and this check
* reports ok.) Pure; exported for tests.
*/
export function computeEmbedConcurrencyCheck(
isLocalEndpoint: boolean,
envValue: string | undefined,
localCap: number,
): Check {
const name = 'embed_concurrency';
if (!isLocalEndpoint) {
return { name, status: 'ok', message: 'Embedding endpoint is not a local inference server — cloud concurrency defaults apply.' };
}
const parsed = envValue ? parseInt(envValue, 10) : NaN;
if (envValue && Number.isFinite(parsed) && parsed > localCap) {
return {
name,
status: 'warn',
message:
`GBRAIN_EMBED_CONCURRENCY=${parsed} against a local embedding endpoint. ` +
`Local inference servers serialize requests, so ${parsed} parallel pages multiply ` +
`latency x${parsed} and can exceed the fetch timeout — the embed backfill stalls ` +
`with no error. Unset GBRAIN_EMBED_CONCURRENCY (auto-caps at ${localCap}) or set it <= ${localCap}.`,
};
}
return {
name,
status: 'ok',
message: `Local embedding endpoint detected; embed concurrency capped at ${envValue ? parsed : localCap}.`,
};
}
/** Thin gateway/env wrapper over `computeEmbedConcurrencyCheck`. */
export async function checkEmbedConcurrency(): Promise<Check> {
try {
const { isLocalEmbeddingEndpoint, LOCAL_EMBED_CONCURRENCY_CAP } = await import('../core/ai/gateway.ts');
return computeEmbedConcurrencyCheck(
isLocalEmbeddingEndpoint(),
process.env.GBRAIN_EMBED_CONCURRENCY,
LOCAL_EMBED_CONCURRENCY_CAP,
);
} catch (err) {
return {
name: 'embed_concurrency',
status: 'ok',
message: `Skipped (${err instanceof Error ? err.message : String(err)})`,
};
}
}
/** Thin env/engine wrapper over `computePoolBudgetCheck`. */
export async function checkPoolBudget(_engine: BrainEngine): Promise<Check> {
try {
+8 -30
View File
@@ -1,6 +1,5 @@
import type { BrainEngine } from '../core/engine.ts';
import { embedBatch, currentEmbeddingSignature } from '../core/embedding.ts';
import { isLocalEmbeddingEndpoint, LOCAL_EMBED_CONCURRENCY_CAP } from '../core/ai/gateway.ts';
import type { ChunkInput } from '../core/types.ts';
import { chunkText } from '../core/chunkers/recursive.ts';
import { createProgress, type ProgressReporter } from '../core/progress.ts';
@@ -177,31 +176,6 @@ export class EmbeddingDimMismatchError extends Error {
}
}
/**
* #2552: resolve the bulk-embed worker count. Env override or the
* cloud-tuned default of 20 — but when the operator did NOT set
* GBRAIN_EMBED_CONCURRENCY and the embedding endpoint is a local inference
* server (Ollama / llama-server / localhost base URL), cap at
* LOCAL_EMBED_CONCURRENCY_CAP: 20 parallel pages against a single-slot
* server serialize on the one loaded model, multiply latency x20 past the
* fetch timeout, and starve the backfill with no surfaced error. An
* explicit env value always wins (`gbrain doctor` warns instead).
* Pacing only ever LOWERS concurrency (Codex P2).
*/
export function resolveEmbedConcurrency(paceMaxConcurrency?: number): number {
const envSet = !!process.env.GBRAIN_EMBED_CONCURRENCY;
const base = parseInt(process.env.GBRAIN_EMBED_CONCURRENCY || '20', 10);
let resolved = base;
if (!envSet && isLocalEmbeddingEndpoint() && base > LOCAL_EMBED_CONCURRENCY_CAP) {
resolved = LOCAL_EMBED_CONCURRENCY_CAP;
serr(
`[embed] local embedding endpoint detected — capping concurrency at ` +
`${LOCAL_EMBED_CONCURRENCY_CAP} (set GBRAIN_EMBED_CONCURRENCY to override)`,
);
}
return paceMaxConcurrency ? Math.min(resolved, paceMaxConcurrency) : resolved;
}
/**
* Pre-flight check: read the actual schema column dim and compare to the
* gateway's resolved dim. Throws `EmbeddingDimMismatchError` on mismatch
@@ -703,8 +677,10 @@ async function embedAll(
// Paced runs lower this to the resolved cap (the real lever vs pooler-slot
// starvation); unpaced keeps the env/default 20. Codex P2: only ever LOWER —
// never raise above an operator's existing env cap.
// #2552: local endpoints auto-cap — see resolveEmbedConcurrency.
const CONCURRENCY = resolveEmbedConcurrency(staleOpts?.paceMaxConcurrency);
const BASE_CONCURRENCY = parseInt(process.env.GBRAIN_EMBED_CONCURRENCY || '20', 10);
const CONCURRENCY = staleOpts?.paceMaxConcurrency
? Math.min(BASE_CONCURRENCY, staleOpts.paceMaxConcurrency)
: BASE_CONCURRENCY;
async function embedOnePage(page: typeof pages[number]) {
// #1737: bail before doing any work for this page if the run was aborted.
@@ -879,8 +855,10 @@ async function embedAllStale(
// Paced runs lower concurrency to the resolved cap (E-1: worker count IS the
// lever on this single pool, no separate permit). Codex P2: pacing only ever
// LOWERS concurrency — never raise above an operator's existing env cap.
// #2552: local endpoints auto-cap — see resolveEmbedConcurrency.
const CONCURRENCY = resolveEmbedConcurrency(staleOpts?.paceMaxConcurrency);
const BASE_CONCURRENCY = parseInt(process.env.GBRAIN_EMBED_CONCURRENCY || '20', 10);
const CONCURRENCY = staleOpts?.paceMaxConcurrency
? Math.min(BASE_CONCURRENCY, staleOpts.paceMaxConcurrency)
: BASE_CONCURRENCY;
const pacer = staleOpts?.pacer ?? createNoopPacer();
// D3 + D3a + D8: wall-clock budget. 30 min default; env override.
+42 -12
View File
@@ -161,7 +161,7 @@ interface ResolveAIOptionsArgs {
nonInteractive: boolean; // --non-interactive (forces D3 fail-loud, no picker)
}
interface ResolvedAIOptions {
export interface ResolvedAIOptions {
embedding_model?: string;
embedding_dimensions?: number;
expansion_model?: string;
@@ -170,6 +170,41 @@ interface ResolvedAIOptions {
noEmbedding?: boolean;
}
/**
* Seed init's AI options from persisted config, falling back to the raw env
* vars when loadConfig() returned null (#1058). On a cold install (no
* config.json AND no DATABASE_URL) loadConfig short-circuits BEFORE its env
* merge, so GBRAIN_EMBEDDING_MODEL / GBRAIN_EMBEDDING_DIMENSIONS /
* GBRAIN_EXPANSION_MODEL / GBRAIN_CHAT_MODEL were silently ignored by init
* and Tier-3 detection auto-picked by API key instead. Exported for unit
* tests (env injectable).
*/
export function seedAIOptionsFromConfig(
cfg: GBrainConfig | null,
env: NodeJS.ProcessEnv = process.env,
): ResolvedAIOptions {
const envDims = env.GBRAIN_EMBEDDING_DIMENSIONS
? parseInt(env.GBRAIN_EMBEDDING_DIMENSIONS, 10)
: NaN;
const seed = cfg ?? {
embedding_disabled: undefined,
embedding_model: env.GBRAIN_EMBEDDING_MODEL,
embedding_dimensions: Number.isFinite(envDims) ? envDims : undefined,
expansion_model: env.GBRAIN_EXPANSION_MODEL,
chat_model: env.GBRAIN_CHAT_MODEL,
};
const out: ResolvedAIOptions = {};
if (seed.embedding_disabled) {
out.noEmbedding = true;
} else if (seed.embedding_model) {
out.embedding_model = seed.embedding_model;
if (seed.embedding_dimensions) out.embedding_dimensions = seed.embedding_dimensions;
}
if (seed.expansion_model) out.expansion_model = seed.expansion_model;
if (seed.chat_model) out.chat_model = seed.chat_model;
return out;
}
/**
* Resolve AI provider options for `gbrain init`.
*
@@ -203,18 +238,13 @@ async function resolveAIOptions(opts: ResolveAIOptionsArgs): Promise<ResolvedAIO
// user already opted into deferred mode.
try {
const { loadConfig } = await import('../core/config.ts');
const cfg = loadConfig();
if (cfg?.embedding_disabled) {
out.noEmbedding = true;
} else if (cfg?.embedding_model) {
out.embedding_model = cfg.embedding_model;
if (cfg.embedding_dimensions) out.embedding_dimensions = cfg.embedding_dimensions;
}
if (cfg?.expansion_model) out.expansion_model = cfg.expansion_model;
if (cfg?.chat_model) out.chat_model = cfg.chat_model;
// #1058: loadConfig() returns null on a cold install (no config.json AND
// no DATABASE_URL) — before it ever reaches its env merge. The seed helper
// falls back to the same GBRAIN_* env vars directly in that case.
Object.assign(out, seedAIOptionsFromConfig(loadConfig()));
} catch {
// loadConfig throws when no brain configured — first-time install, fall
// through to env detection.
// loadConfig threw — treat as first-time install, fall through to env
// detection.
}
// --- Tier 1+2: explicit flags ---------------------------------------------
-27
View File
@@ -683,33 +683,6 @@ export function getEmbeddingDimensions(): number {
return requireConfig().embedding_dimensions ?? DEFAULT_EMBEDDING_DIMENSIONS;
}
/**
* #2552: cap for parallel bulk-embed workers against a local inference
* server. A single-slot Ollama/llama-server serializes requests, so the
* cloud-tuned 20-worker fan-out multiplies latency x20 and blows past the
* fetch timeout with no surfaced error (the backfill silently starves).
*/
export const LOCAL_EMBED_CONCURRENCY_CAP = 2;
/**
* #2552: true when the configured embedding model routes to a local
* inference server — the `ollama` / `llama-server` recipes, or any recipe
* whose base URL was explicitly pointed at localhost. Bulk callers use this
* to pick CPU-safe concurrency defaults; `gbrain doctor` uses it to warn
* about an explicit cloud-sized override. Fail-open: unconfigured or
* unresolvable gateway → false (cloud behavior, the historical default).
*/
export function isLocalEmbeddingEndpoint(): boolean {
try {
const { recipe } = resolveRecipe(getEmbeddingModel());
if (recipe.id === 'ollama' || recipe.id === 'llama-server') return true;
const base = requireConfig().base_urls?.[recipe.id] ?? '';
return /\/\/(localhost|127\.0\.0\.1|\[::1\])(:|\/|$)/i.test(base);
} catch {
return false;
}
}
/**
* v0.28.11: returns the configured multimodal embedding model when set,
* or undefined if the brain falls back to `embedding_model` for multimodal
+3 -11
View File
@@ -29,17 +29,9 @@ export const ollama: Recipe = {
trust_custom_dims: true, // #2271: local models carry varied native dims
cost_per_1m_tokens_usd: 0,
price_last_verified: '2026-04-20',
// #2552: Ollama's true batch capacity depends on the locally loaded
// model + OLLAMA_NUM_PARALLEL, but the previous `no_batch_cap: true`
// meant a whole page went out in ONE request — on a CPU-only box that
// multiplies latency past the fetch timeout and the backfill starves
// with no surfaced error. Ollama doesn't return a recognizable
// token-limit error either, so the recursive-halving safety net never
// fires; a conservative static pre-split cap is the only guard.
// 4096 tokens x 2 chars/token ~= 8K chars per request (code-dense
// pages run ~2 chars/token, not the tiktoken-ish 4).
max_batch_tokens: 4096,
chars_per_token: 2,
// Ollama's batch capacity depends on the locally loaded model + the
// OLLAMA_NUM_PARALLEL config; no static cap to declare. v0.32 (#779).
no_batch_cap: true,
},
},
setup_hint: 'Install Ollama from https://ollama.ai, then `ollama pull nomic-embed-text` and `ollama serve`.',
-1
View File
@@ -141,7 +141,6 @@ export const OPS_CHECK_NAMES: ReadonlySet<string> = new Set([
'pgbouncer_prepare',
'pgvector',
'pool_budget',
'embed_concurrency',
'progressive_batch_audit_health',
'queue_health',
'reranker_health',
+19 -3
View File
@@ -332,6 +332,15 @@ export interface OperationContext {
* remote/untrusted (defense in depth in case the type is bypassed via cast).
*/
remote: boolean;
/**
* Transport marker for auth-less remote surfaces (#1061). The stdio MCP
* dispatch sets 'stdio' — it is deliberately `remote: true` (agent-facing,
* untrusted) but has no per-token auth (local pipe), so identity ops like
* whoami need a way to distinguish "known auth-less transport" from "a
* transport bug forgot to thread ctx.auth". Trust decisions MUST NOT key
* off this field — only `ctx.remote === false` grants trust.
*/
transport?: 'stdio';
/**
* Subagent runtime context (v0.16+). Set by the subagent tool dispatcher when
* dispatching an op as a tool call from an LLM loop. Used to enforce per-op
@@ -3713,9 +3722,10 @@ const whoami: Operation = {
'Introspect the calling identity. Returns one of three transport shapes: ' +
'{transport: "oauth", client_id, client_name, scopes, expires_at}, ' +
'{transport: "legacy", token_name, scopes, expires_at: null}, or ' +
'{transport: "local", scopes: []}. Throws unknown_transport when the ' +
'context is ambiguous (remote=true without auth) — fail-closed posture ' +
'mirroring the v0.26.9 trust-boundary contract.',
'{transport: "local", scopes: []}, or {transport: "stdio", scopes: []} ' +
'for the auth-less stdio MCP pipe. Throws unknown_transport when the ' +
'context is ambiguous (remote=true without auth and no transport marker) ' +
'— fail-closed posture mirroring the v0.26.9 trust-boundary contract.',
params: {},
scope: 'read',
handler: async (ctx) => {
@@ -3727,6 +3737,12 @@ const whoami: Operation = {
if (ctx.remote === false) {
return { transport: 'local', scopes: [] };
}
// #1061: stdio MCP is remote/untrusted by design but has no per-token
// auth (local pipe) — a known transport, not a bug. Report it instead of
// throwing. Empty scopes: nothing here may be used to gate anything.
if (!ctx.auth && ctx.transport === 'stdio') {
return { transport: 'stdio', scopes: [] };
}
if (!ctx.auth) {
throw new OperationError(
'unknown_transport',
+7 -16
View File
@@ -56,7 +56,7 @@ import { GBrainError, PAGE_SORT_SQL, ENRICH_ORDER_SQL } from './types.ts';
import { finalizeLastSeen } from './chronicle/last-seen.ts';
import { computeAnomaliesFromBuckets } from './cycle/anomaly.ts';
import { resolveBoostMap, resolveHardExcludes } from './search/source-boost.ts';
import { buildSourceFactorCase, buildHardExcludeClause, buildVisibilityClause, buildRecencyComponentSql, buildBestPerPagePoolCte, buildOrFallbackWebsearchQuery, buildWebsearchQueryExpr } from './search/sql-ranking.ts';
import { buildSourceFactorCase, buildHardExcludeClause, buildVisibilityClause, buildRecencyComponentSql, buildBestPerPagePoolCte, buildOrFallbackWebsearchQuery } from './search/sql-ranking.ts';
import {
normalizeEngineColumn,
buildVectorCastFragment,
@@ -1591,8 +1591,6 @@ export class PGLiteEngine implements BrainEngine {
}
// v0.20.0 Cathedral II Layer 10 C1/C2: language + symbol-kind filters.
// #2380: slash-bearing queries match both the split-word and literal
// slash forms — see buildWebsearchQueryExpr in ./search/sql-ranking.ts.
const params: unknown[] = [query, innerLimit, limit, offset];
let extraFilter = '';
if (opts?.language) {
@@ -1632,7 +1630,6 @@ export class PGLiteEngine implements BrainEngine {
// FTS config name (e.g. 'english', 'pt_br'). Validated by getFtsLanguage()
// — safe to interpolate into raw SQL.
const ftsLang = getFtsLanguage();
const ftsQueryExpr = buildWebsearchQueryExpr(ftsLang, '$1', query);
const keywordSql =
`WITH ranked AS (
@@ -1640,14 +1637,14 @@ export class PGLiteEngine implements BrainEngine {
p.slug, p.id as page_id, p.title, p.type, p.source_id,
p.effective_date, p.effective_date_source,
cc.id as chunk_id, cc.chunk_index, cc.chunk_text, cc.chunk_source,
ts_rank(cc.search_vector, ${ftsQueryExpr}) * ${sourceFactorCase} AS score,
ts_rank(cc.search_vector, websearch_to_tsquery('${ftsLang}', $1)) * ${sourceFactorCase} AS score,
CASE WHEN p.updated_at < (
SELECT MAX(te.created_at) FROM timeline_entries te WHERE te.page_id = p.id
) THEN true ELSE false END AS stale
FROM content_chunks cc
JOIN pages p ON p.id = cc.page_id
JOIN sources s ON s.id = p.source_id
WHERE cc.search_vector @@ ${ftsQueryExpr} ${detailFilter}${extraFilter} ${hardExcludeClause} ${visibilityClause}
WHERE cc.search_vector @@ websearch_to_tsquery('${ftsLang}', $1) ${detailFilter}${extraFilter} ${hardExcludeClause} ${visibilityClause}
-- v0.27.1: hide image rows from default text-keyword search so
-- OCR text doesn't drown text-page hits. Image-similarity queries
-- run a separate vector path on embedding_image.
@@ -1715,10 +1712,7 @@ export class PGLiteEngine implements BrainEngine {
// FTS config name (e.g. 'english', 'pt_br'). Validated by getFtsLanguage()
// — safe to interpolate into raw SQL.
const ftsLang = getFtsLanguage();
const ftsQueryExpr = buildWebsearchQueryExpr(ftsLang, '$1', query);
// #2380: slash-bearing queries match both the split-word and literal
// slash forms — see buildWebsearchQueryExpr in ./search/sql-ranking.ts.
const params: unknown[] = [query, limit, offset];
let extraFilter = '';
if (opts?.type) {
@@ -1766,7 +1760,7 @@ export class PGLiteEngine implements BrainEngine {
COALESCE(rep.chunk_index, 0) as chunk_index,
COALESCE(rep.chunk_text, '') as chunk_text,
COALESCE(rep.chunk_source, 'compiled_truth') as chunk_source,
ts_rank_cd(p.search_vector, ${ftsQueryExpr}) * ${sourceFactorCase} AS score,
ts_rank_cd(p.search_vector, websearch_to_tsquery('${ftsLang}', $1)) * ${sourceFactorCase} AS score,
CASE WHEN p.updated_at < (
SELECT MAX(te.created_at) FROM timeline_entries te WHERE te.page_id = p.id
) THEN true ELSE false END AS stale
@@ -1781,7 +1775,7 @@ export class PGLiteEngine implements BrainEngine {
ORDER BY (cc.chunk_source = 'compiled_truth') DESC, cc.chunk_index ASC
LIMIT 1
) rep ON true
WHERE p.search_vector @@ ${ftsQueryExpr}
WHERE p.search_vector @@ websearch_to_tsquery('${ftsLang}', $1)
${extraFilter} ${hardExcludeClause} ${visibilityClause}
ORDER BY score DESC, p.id ASC
LIMIT $2 OFFSET $3`;
@@ -1968,8 +1962,6 @@ export class PGLiteEngine implements BrainEngine {
});
}
// #2380: slash-bearing queries match both the split-word and literal
// slash forms — see buildWebsearchQueryExpr in ./search/sql-ranking.ts.
const params: unknown[] = [query, limit, offset];
let extraFilter = '';
if (opts?.language) {
@@ -2004,21 +1996,20 @@ export class PGLiteEngine implements BrainEngine {
// FTS config name (e.g. 'english', 'pt_br'). Validated by getFtsLanguage()
// — safe to interpolate into raw SQL.
const ftsLang = getFtsLanguage();
const ftsQueryExpr = buildWebsearchQueryExpr(ftsLang, '$1', query);
const { rows } = await this.db.query(
`SELECT
p.slug, p.id as page_id, p.title, p.type, p.source_id,
p.effective_date, p.effective_date_source,
cc.id as chunk_id, cc.chunk_index, cc.chunk_text, cc.chunk_source,
ts_rank(cc.search_vector, ${ftsQueryExpr}) * ${sourceFactorCase} AS score,
ts_rank(cc.search_vector, websearch_to_tsquery('${ftsLang}', $1)) * ${sourceFactorCase} AS score,
CASE WHEN p.updated_at < (
SELECT MAX(te.created_at) FROM timeline_entries te WHERE te.page_id = p.id
) THEN true ELSE false END AS stale
FROM content_chunks cc
JOIN pages p ON p.id = cc.page_id
JOIN sources s ON s.id = p.source_id
WHERE cc.search_vector @@ ${ftsQueryExpr} ${detailFilter}${extraFilter} ${hardExcludeClause} ${visibilityClause}
WHERE cc.search_vector @@ websearch_to_tsquery('${ftsLang}', $1) ${detailFilter}${extraFilter} ${hardExcludeClause} ${visibilityClause}
ORDER BY score DESC
LIMIT $2 OFFSET $3`,
params
+7 -16
View File
@@ -64,7 +64,7 @@ import { ConnectionManager } from './connection-manager.ts';
import { logConnectionEvent } from './connection-audit.ts';
import { validateSlug, contentHash, rowToPage, rowToStalePage, rowToChunk, rowToSearchResult, parseEmbedding, tryParseEmbedding, takeRowToTake, takeHitRowToHit, isUndefinedTableError, warnOncePerProcess } from './utils.ts';
import { resolveBoostMap, resolveHardExcludes } from './search/source-boost.ts';
import { buildSourceFactorCase, buildHardExcludeClause, buildVisibilityClause, buildRecencyComponentSql, buildBestPerPagePoolCte, buildOrFallbackWebsearchQuery, buildWebsearchQueryExpr } from './search/sql-ranking.ts';
import { buildSourceFactorCase, buildHardExcludeClause, buildVisibilityClause, buildRecencyComponentSql, buildBestPerPagePoolCte, buildOrFallbackWebsearchQuery } from './search/sql-ranking.ts';
import { DEFAULT_EMBEDDING_MODEL, DEFAULT_EMBEDDING_DIMENSIONS } from './ai/defaults.ts';
import { DELETE_BATCH_SIZE } from './engine-constants.ts';
@@ -1691,8 +1691,6 @@ export class PostgresEngine implements BrainEngine {
const hardExcludePrefixes = resolveHardExcludes(opts?.exclude_slug_prefixes, opts?.include_slug_prefixes);
const hardExcludeClause = buildHardExcludeClause('p.slug', hardExcludePrefixes);
// #2380: slash-bearing queries match both the split-word and literal
// slash forms — see buildWebsearchQueryExpr in ./search/sql-ranking.ts.
const params: unknown[] = [query];
let typeClause = '';
if (type) {
@@ -1763,7 +1761,6 @@ export class PostgresEngine implements BrainEngine {
// FTS config name (e.g. 'english', 'pt_br'). Validated by getFtsLanguage()
// — safe to interpolate into raw SQL.
const ftsLang = getFtsLanguage();
const ftsQueryExpr = buildWebsearchQueryExpr(ftsLang, '$1', query);
const rawQuery = `
WITH ranked_chunks AS (
@@ -1771,11 +1768,11 @@ export class PostgresEngine implements BrainEngine {
p.slug, p.id as page_id, p.title, p.type, p.source_id,
p.effective_date, p.effective_date_source,
cc.id as chunk_id, cc.chunk_index, cc.chunk_text, cc.chunk_source,
ts_rank(cc.search_vector, ${ftsQueryExpr}) * ${sourceFactorCase} AS score
ts_rank(cc.search_vector, websearch_to_tsquery('${ftsLang}', $1)) * ${sourceFactorCase} AS score
FROM content_chunks cc
JOIN pages p ON p.id = cc.page_id
JOIN sources s ON s.id = p.source_id
WHERE cc.search_vector @@ ${ftsQueryExpr}
WHERE cc.search_vector @@ websearch_to_tsquery('${ftsLang}', $1)
${typeClause}
${typesClause}
${excludeSlugsClause}
@@ -1866,10 +1863,7 @@ export class PostgresEngine implements BrainEngine {
// FTS config name (e.g. 'english', 'pt_br'). Validated by getFtsLanguage()
// — safe to interpolate into raw SQL.
const ftsLang = getFtsLanguage();
const ftsQueryExpr = buildWebsearchQueryExpr(ftsLang, '$1', query);
// #2380: slash-bearing queries match both the split-word and literal
// slash forms — see buildWebsearchQueryExpr in ./search/sql-ranking.ts.
const params: unknown[] = [query];
let typeClause = '';
if (opts?.type) {
@@ -1929,7 +1923,7 @@ export class PostgresEngine implements BrainEngine {
COALESCE(rep.chunk_index, 0) as chunk_index,
COALESCE(rep.chunk_text, '') as chunk_text,
COALESCE(rep.chunk_source, 'compiled_truth') as chunk_source,
ts_rank_cd(p.search_vector, ${ftsQueryExpr}) * ${sourceFactorCase} AS score,
ts_rank_cd(p.search_vector, websearch_to_tsquery('${ftsLang}', $1)) * ${sourceFactorCase} AS score,
false AS stale
FROM pages p
JOIN sources s ON s.id = p.source_id
@@ -1942,7 +1936,7 @@ export class PostgresEngine implements BrainEngine {
ORDER BY (cc.chunk_source = 'compiled_truth') DESC, cc.chunk_index ASC
LIMIT 1
) rep ON true
WHERE p.search_vector @@ ${ftsQueryExpr}
WHERE p.search_vector @@ websearch_to_tsquery('${ftsLang}', $1)
${typeClause}
${typesClause}
${excludeSlugsClause}
@@ -2006,8 +2000,6 @@ export class PostgresEngine implements BrainEngine {
const hardExcludePrefixes = resolveHardExcludes(opts?.exclude_slug_prefixes, opts?.include_slug_prefixes);
const hardExcludeClause = buildHardExcludeClause('p.slug', hardExcludePrefixes);
// #2380: slash-bearing queries match both the split-word and literal
// slash forms — see buildWebsearchQueryExpr in ./search/sql-ranking.ts.
const params: unknown[] = [query];
let typeClause = '';
if (type) {
@@ -2068,19 +2060,18 @@ export class PostgresEngine implements BrainEngine {
// FTS config name (e.g. 'english', 'pt_br'). Validated by getFtsLanguage()
// — safe to interpolate into raw SQL.
const ftsLang = getFtsLanguage();
const ftsQueryExpr = buildWebsearchQueryExpr(ftsLang, '$1', query);
const rawQuery = `
SELECT
p.slug, p.id as page_id, p.title, p.type, p.source_id,
p.effective_date, p.effective_date_source,
cc.id as chunk_id, cc.chunk_index, cc.chunk_text, cc.chunk_source,
ts_rank(cc.search_vector, ${ftsQueryExpr}) * ${sourceFactorCase} AS score,
ts_rank(cc.search_vector, websearch_to_tsquery('${ftsLang}', $1)) * ${sourceFactorCase} AS score,
false AS stale
FROM content_chunks cc
JOIN pages p ON p.id = cc.page_id
JOIN sources s ON s.id = p.source_id
WHERE cc.search_vector @@ ${ftsQueryExpr}
WHERE cc.search_vector @@ websearch_to_tsquery('${ftsLang}', $1)
${typeClause}
${typesClause}
${excludeSlugsClause}
-22
View File
@@ -251,28 +251,6 @@ export function buildOrFallbackWebsearchQuery(query: string): string | null {
return tokens.join(' OR ');
}
/**
* #2380: FTS query expression for slash-bearing queries. Postgres' default
* text-search parser classifies `foo/bar` as a single `file`-alias lexeme
* on BOTH the query side and the index side. So a raw `foo/bar` query only
* matched documents carrying the identical joined lexeme (literal paths),
* and a slash-split query only matches documents whose text had the words
* separated. Neither form alone covers both document shapes; OR the two
* parses so a slash query matches prose ("foo and bar", stemmed, AND
* semantics) AND literal slash forms ("src/core/x.ts") alike.
*
* Slash-free queries return the plain single-parse expression byte-
* identical SQL and identical ts_rank to the historical behavior.
*
* `ftsLang` is validated by getFtsLanguage() (safe to interpolate);
* `param` is a `$N` placeholder, never user text.
*/
export function buildWebsearchQueryExpr(ftsLang: string, param: string, query: string): string {
const plain = `websearch_to_tsquery('${ftsLang}', ${param})`;
if (!query.includes('/')) return plain;
return `(websearch_to_tsquery('${ftsLang}', translate(${param}, '/', ' ')) || ${plain})`;
}
// ============================================================
// v0.29.1 — Recency component SQL builder
// ============================================================
+7
View File
@@ -32,6 +32,12 @@ export interface DispatchOpts {
remote?: boolean;
/** Override the default stderr logger (e.g. CLI uses console.* directly). */
logger?: OperationContext['logger'];
/**
* #1061: transport marker for auth-less remote surfaces. The stdio MCP
* server passes 'stdio' so identity ops (whoami) can report the transport
* instead of throwing unknown_transport. Never used for trust decisions.
*/
transport?: OperationContext['transport'];
/**
* v0.28: per-token allow-list for the takes.holder field. Threaded by
* the HTTP/stdio transport from `access_tokens.permissions.takes_holders`.
@@ -203,6 +209,7 @@ export function buildOperationContext(
logger: opts.logger || stderrLogger,
dryRun: !!params.dry_run,
remote: opts.remote ?? true,
transport: opts.transport,
takesHoldersAllowList: opts.takesHoldersAllowList,
// v0.34 D4: sourceId is REQUIRED at the type level. Auto-fill 'default'
// for single-source brains and any caller who didn't resolve a sourceId.
+4
View File
@@ -42,6 +42,10 @@ export async function startMcpServer(engine: BrainEngine) {
// `gbrain call <op>` (sets remote=false in src/cli.ts).
return dispatchToolCall(engine, name, params, {
remote: true,
// #1061: mark the transport so whoami can report {transport: 'stdio'}
// instead of throwing unknown_transport. Trust posture unchanged —
// stdio stays remote/untrusted.
transport: 'stdio',
takesHoldersAllowList: ['world'],
// v0.31: source defaults to 'default' for stdio (no per-token scope).
// Operators who want a different source on stdio MCP should set
@@ -28,8 +28,8 @@ describe('v0.32 #779: no_batch_cap suppresses the missing-max_batch_tokens warni
resetGateway();
});
test('LiteLLM and llama-server declare no_batch_cap: true', () => {
for (const id of ['litellm', 'llama-server']) {
test('Ollama, LiteLLM, llama-server all declare no_batch_cap: true', () => {
for (const id of ['ollama', 'litellm', 'llama-server']) {
const r = getRecipe(id);
expect(r, `${id} not registered`).toBeDefined();
expect(
@@ -39,18 +39,6 @@ describe('v0.32 #779: no_batch_cap suppresses the missing-max_batch_tokens warni
}
});
test('#2552: Ollama declares a conservative static batch cap, not no_batch_cap', () => {
// A CPU-only Ollama box wedges when a whole page ships in one request;
// Ollama never returns a token-limit error so the recursive-halving
// safety net can't fire. The pre-split cap is the only guard.
const r = getRecipe('ollama');
expect(r).toBeDefined();
const e = r!.touchpoints.embedding!;
expect(e.no_batch_cap).toBeUndefined();
expect(e.max_batch_tokens).toBe(4096);
expect(e.chars_per_token).toBe(2);
});
test('configureGateway does NOT warn for ollama/litellm/llama-server', () => {
warnSpy.mockClear();
resetGateway();
-118
View File
@@ -1,118 +0,0 @@
/**
* #2552: cloud-tuned embedding defaults silently wedge CPU-only local
* endpoints (Ollama). Three-part fix under test:
*
* 1. `isLocalEmbeddingEndpoint()` gateway helper detecting local
* inference servers (ollama / llama-server recipes, localhost base URL).
* 2. `resolveEmbedConcurrency()` embed auto-caps the 20-worker fan-out
* at LOCAL_EMBED_CONCURRENCY_CAP for local endpoints unless the
* operator set GBRAIN_EMBED_CONCURRENCY explicitly.
* 3. `computeEmbedConcurrencyCheck()` doctor warns when an explicit env
* override fans out against a local endpoint.
*
* Serial: mutates process.env and the module-global gateway config.
*/
import { afterAll, afterEach, describe, expect, test } from 'bun:test';
import {
configureGateway,
resetGateway,
isLocalEmbeddingEndpoint,
LOCAL_EMBED_CONCURRENCY_CAP,
} from '../src/core/ai/gateway.ts';
import { resolveEmbedConcurrency } from '../src/commands/embed.ts';
import { computeEmbedConcurrencyCheck } from '../src/commands/doctor.ts';
const SAVED_ENV = process.env.GBRAIN_EMBED_CONCURRENCY;
afterEach(() => {
resetGateway();
if (SAVED_ENV === undefined) delete process.env.GBRAIN_EMBED_CONCURRENCY;
else process.env.GBRAIN_EMBED_CONCURRENCY = SAVED_ENV;
});
afterAll(() => {
resetGateway();
});
describe('#2552 isLocalEmbeddingEndpoint', () => {
test('false when the gateway is not configured (fail-open to cloud behavior)', () => {
resetGateway();
expect(isLocalEmbeddingEndpoint()).toBe(false);
});
test('true for the ollama recipe', () => {
configureGateway({ embedding_model: 'ollama:nomic-embed-text', env: {} });
expect(isLocalEmbeddingEndpoint()).toBe(true);
});
test('true for the llama-server recipe', () => {
configureGateway({ embedding_model: 'llama-server:my-gguf', env: {} });
expect(isLocalEmbeddingEndpoint()).toBe(true);
});
test('false for a cloud recipe', () => {
configureGateway({
embedding_model: 'openai:text-embedding-3-small',
env: { OPENAI_API_KEY: 'fake' },
});
expect(isLocalEmbeddingEndpoint()).toBe(false);
});
test('true when a cloud recipe base URL is explicitly pointed at localhost', () => {
configureGateway({
embedding_model: 'openai:text-embedding-3-small',
env: { OPENAI_API_KEY: 'fake' },
base_urls: { openai: 'http://localhost:8080/v1' },
});
expect(isLocalEmbeddingEndpoint()).toBe(true);
});
});
describe('#2552 resolveEmbedConcurrency', () => {
test('caps at LOCAL_EMBED_CONCURRENCY_CAP for a local endpoint when env is unset', () => {
delete process.env.GBRAIN_EMBED_CONCURRENCY;
configureGateway({ embedding_model: 'ollama:nomic-embed-text', env: {} });
expect(resolveEmbedConcurrency()).toBe(LOCAL_EMBED_CONCURRENCY_CAP);
});
test('explicit env override always wins, even against a local endpoint', () => {
process.env.GBRAIN_EMBED_CONCURRENCY = '10';
configureGateway({ embedding_model: 'ollama:nomic-embed-text', env: {} });
expect(resolveEmbedConcurrency()).toBe(10);
});
test('cloud endpoints keep the historical default of 20', () => {
delete process.env.GBRAIN_EMBED_CONCURRENCY;
configureGateway({ env: { OPENAI_API_KEY: 'fake' } });
expect(resolveEmbedConcurrency()).toBe(20);
});
test('pacing only ever lowers concurrency', () => {
delete process.env.GBRAIN_EMBED_CONCURRENCY;
configureGateway({ embedding_model: 'ollama:nomic-embed-text', env: {} });
expect(resolveEmbedConcurrency(1)).toBe(1);
expect(resolveEmbedConcurrency(16)).toBe(LOCAL_EMBED_CONCURRENCY_CAP);
});
});
describe('#2552 computeEmbedConcurrencyCheck (doctor)', () => {
test('ok for non-local endpoints', () => {
expect(computeEmbedConcurrencyCheck(false, '20', 2).status).toBe('ok');
});
test('warn when an explicit override exceeds the local cap', () => {
const check = computeEmbedConcurrencyCheck(true, '20', 2);
expect(check.status).toBe('warn');
expect(check.message).toContain('GBRAIN_EMBED_CONCURRENCY=20');
});
test('ok when env is unset against a local endpoint (auto-cap applies)', () => {
expect(computeEmbedConcurrencyCheck(true, undefined, 2).status).toBe('ok');
});
test('ok when the override is at or under the cap', () => {
expect(computeEmbedConcurrencyCheck(true, '2', 2).status).toBe('ok');
expect(computeEmbedConcurrencyCheck(true, '1', 2).status).toBe('ok');
});
});
+45 -1
View File
@@ -12,7 +12,7 @@
*/
import { describe, test, expect } from 'bun:test';
import { groupReadyByProvider, findEnvKeyTypos } from '../src/commands/init.ts';
import { groupReadyByProvider, findEnvKeyTypos, seedAIOptionsFromConfig } from '../src/commands/init.ts';
describe('groupReadyByProvider — embedding touchpoint', () => {
test('OPENAI_API_KEY alone → openai is ready', async () => {
@@ -149,3 +149,47 @@ describe('findEnvKeyTypos', () => {
expect(got.find(t => t.userSet === 'COMPLETELY_UNRELATED_KEY')).toBeUndefined();
});
});
describe('seedAIOptionsFromConfig — #1058 cold-install env fallback', () => {
test('null config (no config.json, no DATABASE_URL) falls back to GBRAIN_* env vars', () => {
const got = seedAIOptionsFromConfig(null, {
GBRAIN_EMBEDDING_MODEL: 'voyage:voyage-3-large',
GBRAIN_EMBEDDING_DIMENSIONS: '1024',
GBRAIN_EXPANSION_MODEL: 'openai:gpt-5-mini',
GBRAIN_CHAT_MODEL: 'anthropic:claude-sonnet-4-6',
});
expect(got.embedding_model).toBe('voyage:voyage-3-large');
expect(got.embedding_dimensions).toBe(1024);
expect(got.expansion_model).toBe('openai:gpt-5-mini');
expect(got.chat_model).toBe('anthropic:claude-sonnet-4-6');
});
test('null config + no env vars → empty seed (Tier-3 detection takes over)', () => {
const got = seedAIOptionsFromConfig(null, {});
expect(got).toEqual({});
});
test('persisted config wins (loadConfig already merged env when non-null)', () => {
const got = seedAIOptionsFromConfig(
{ engine: 'pglite', embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: 1536 } as any,
{ GBRAIN_EMBEDDING_MODEL: 'voyage:voyage-3-large' },
);
expect(got.embedding_model).toBe('openai:text-embedding-3-small');
expect(got.embedding_dimensions).toBe(1536);
});
test('embedding_disabled sentinel honored on re-init', () => {
const got = seedAIOptionsFromConfig({ engine: 'pglite', embedding_disabled: true } as any, {});
expect(got.noEmbedding).toBe(true);
expect(got.embedding_model).toBeUndefined();
});
test('non-numeric GBRAIN_EMBEDDING_DIMENSIONS ignored, model still seeds', () => {
const got = seedAIOptionsFromConfig(null, {
GBRAIN_EMBEDDING_MODEL: 'voyage:voyage-3-large',
GBRAIN_EMBEDDING_DIMENSIONS: 'not-a-number',
});
expect(got.embedding_model).toBe('voyage:voyage-3-large');
expect(got.embedding_dimensions).toBeUndefined();
});
});
-61
View File
@@ -216,67 +216,6 @@ describe('PGLiteEngine: Search', () => {
expect(results.length).toBe(0);
});
// Regression (#2380): queries containing `/` used to bypass FTS AND
// semantics. Postgres' default text-search parser classifies `foo/bar` as
// a `file`-alias token mapped to the `simple` dictionary, so it became a
// single un-stemmed lexeme `'foo/bar'` that never matches indexed text —
// the primary FTS pass returned 0 and the OR fallback took over, matching
// pages that contain EITHER term. searchKeyword/searchTitles now normalize
// `/` to whitespace before websearch_to_tsquery parses, so the primary
// AND pass matches directly.
test('searchKeyword: slash query matches with AND semantics, not OR fallback', async () => {
// Decoy shares only ONE of the two query terms ('enterprise').
await engine.putPage('concepts/enterprise-pricing', {
type: 'concept', title: 'Widget Pricing',
compiled_truth: 'Enterprise pricing for widgets.',
});
await engine.upsertChunks('concepts/enterprise-pricing', [
{ chunk_index: 0, chunk_text: 'Enterprise pricing for widgets', chunk_source: 'compiled_truth' },
]);
// Both terms co-occur only in the novamind chunk. Pre-fix this returned
// BOTH pages (primary pass zero-hit → OR fallback); post-fix the primary
// AND pass returns exactly the co-occurrence page.
const results = await engine.searchKeyword('NovaMind/enterprise');
expect(results.length).toBe(1);
expect(results[0].slug).toBe('companies/novamind');
});
test('searchTitles: slash query matches with AND semantics, not OR fallback', async () => {
await engine.putPage('companies/novamind-enterprise', {
type: 'company', title: 'NovaMind Enterprise Platform',
compiled_truth: 'Placeholder body.',
});
await engine.putPage('guides/enterprise-sales', {
type: 'concept', title: 'Enterprise Sales Guide',
compiled_truth: 'Placeholder body.',
});
// Pre-fix: `NovaMind/Enterprise` parsed as one file-alias lexeme → the
// primary title pass returned 0 and the OR fallback matched BOTH titles.
const results = await engine.searchTitles('NovaMind/Enterprise');
expect(results.length).toBe(1);
expect(results[0].slug).toBe('companies/novamind-enterprise');
});
test('searchKeyword: slash query still matches the literal slash form (file paths)', async () => {
// The INDEX side also emits the joined file-alias lexeme for literal
// `foo/bar` text, so a query normalized to split words alone would go
// blind to documents containing the literal slash form (paths, URLs).
// buildWebsearchQueryExpr ORs both parses; this pins the raw arm.
await engine.putPage('runbooks/widget-deploy', {
type: 'concept', title: 'Widget Deploy Runbook',
compiled_truth: 'Runbook for the acme/widget deployment pipeline.',
});
await engine.upsertChunks('runbooks/widget-deploy', [
{ chunk_index: 0, chunk_text: 'Runbook for the acme/widget deployment pipeline', chunk_source: 'compiled_truth' },
]);
const results = await engine.searchKeyword('acme/widget');
expect(results.length).toBe(1);
expect(results[0].slug).toBe('runbooks/widget-deploy');
});
test('tsvector trigger populates search_vector on insert', async () => {
// Verify the PL/pgSQL trigger fires and content_chunks.search_vector is
// populated from chunk_text. v0.20.0 Cathedral II Layer 3 moved FTS from
+29
View File
@@ -94,6 +94,35 @@ describe('whoami op contract', () => {
expect(result.expires_at).toBeNull();
});
// #1061: stdio MCP is remote/untrusted by design but has no per-token auth
// (local pipe). The stdio dispatch marks ctx.transport='stdio'; whoami
// reports it instead of throwing unknown_transport.
test('stdio transport (remote=true, no auth, transport marker) reports stdio', async () => {
const result = (await whoami.handler(
ctxWith({ remote: true, auth: undefined, transport: 'stdio' }),
{},
)) as any;
expect(result.transport).toBe('stdio');
expect(result.scopes).toEqual([]);
});
test('stdio marker does not mask real auth (auth still wins)', async () => {
const result = (await whoami.handler(
ctxWith({
remote: true,
transport: 'stdio',
auth: {
token: 'gbrain_at_xxx',
clientId: 'gbrain_cl_abc',
scopes: ['read'],
expiresAt: 1,
} as AuthInfo,
}),
{},
)) as any;
expect(result.transport).toBe('oauth');
});
// Q3: ambiguous transport — fail-closed. The footgun this guards against
// is a future transport that lands without threading auth, where a buggy
// caller might trust whoami's output to gate sensitive ops.