Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { execSync } from '../core/spawn.ts';
import { readdirSync, lstatSync, existsSync, copyFileSync, mkdirSync, readFileSync } from 'fs';
import { join, dirname } from 'path';
import { fileURLToPath } from 'url';
import { homedir } from 'os';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
import { saveConfig, loadConfig, loadConfigFileOnly, toEngineConfig, gbrainPath, configPath, isThinClient, effectiveEnvDatabaseUrl, type GBrainConfig } from '../core/config.ts';
import { createEngine } from '../core/engine-factory.ts';
import { discoverOAuth, mintClientCredentialsToken, smokeTestMcp } from '../core/remote-mcp-probe.ts';
import { runInitEmbedCheck } from '../core/init-embed-check.ts';
import { PgliteBusyError } from '../core/pglite-lock.ts';
import { inspectRemoteInitState, preserveConversionConfig, readInitConfigState, printInAgentReady } from '../core/agent-install/init-state.ts';
import { isNewContentDatabase, setupSharedBrainContent, type SharedContentOptions } from '../core/shared-skills/setup.ts';
import { resolveSourceId } from '../core/source-resolver.ts';
import type { BrainEngine } from '../core/engine.ts';
import { readPrimaryEmbeddingStores, readStoredEmbeddingIdentity } from '../core/stored-embedding-identity.ts';
import { deferInitJsonError, flushInitJsonResult, initJsonError, setInitJsonResult, writeDeferredInitJsonError } from './init-json.ts';
import { deferredEmbeddingHint, firstRunBundle, firstRunJson, harnessRegistrationCommand } from './init-first-run.ts';
import { keptEmbeddingIdentity, keptEmbeddingNotice, recordInitEmbedding } from './init-embedding-plane.ts';
import { writeCliNotices } from '../core/interop-notices.ts';
import { exitCodeForCode } from '../core/error-catalogue.ts';
import { promptLineStderr } from '../core/interaction.ts';
import type { SearchMode as SearchModeName } from '../core/search/mode.ts';
import type { McpSurface } from '../mcp/surface.ts';
/** D2: `--json` writes exactly one document, after whichever branch ran (see init-json.ts). */
export async function runInit(args: string[]) {
const fresh = !existsSync(configPath());
await runInitBranches(args);
if (fresh && existsSync(configPath())) (await import('../core/funnel.ts')).recordFunnelEvent('clean_install');
if (args.includes('--json')) await flushInitJsonResult();
}
async function runInitBranches(args: string[]) {
// Help guard: cli.ts only routes --help to printOpHelp() for shared-op
// commands; CLI_ONLY commands (init, embed, etc.) fall through to their
// handler with --help in argv. Without this guard, `gbrain init --help`
// proceeds into the smart-detection branch below, scans cwd for .md files,
// and on a directory with 1000+ files (e.g. $HOME for someone whose brain
// and notes share a root) silently overwrites the existing Supabase config
// with a fresh PGLite brain at ~/.gbrain/brain.pglite. Confirmed in the
// wild — flipped a working `engine: postgres` config to `engine: pglite`
// on a brain with 10K+ pages. Help should never mutate state.
if (args.includes('--help') || args.includes('-h')) {
printInitHelp();
return;
}
validateInitFlags(args);
registrationSurface = (await import('../mcp/surface.ts')).parseSurfaceFlag(args) ?? undefined;
searchModeChoice = (await import('./init-mode-picker.ts')).searchModeChoiceFromArgs(args, failInitFlag);
const isSupabase = args.includes('--supabase');
const isPGLite = args.includes('--pglite');
const isMcpOnly = args.includes('--mcp-only');
const isForce = args.includes('--force');
const isNonInteractive = args.includes('--non-interactive');
const isMigrateOnly = args.includes('--migrate-only');
const jsonOutput = args.includes('--json');
const fileState = readInitConfigState(jsonOutput, jsonOutput ? message => process.exit(initJsonError({ status: 'error', reason: 'invalid_existing_config', message },
'config_error', message, `Repair or move ${configPath()} aside, then re-run gbrain init.`)) : undefined);
const urlIndex = args.indexOf('--url');
const manualUrl = urlIndex !== -1 ? args[urlIndex + 1] : null;
const keyIndex = args.indexOf('--key');
const apiKey = keyIndex !== -1 ? args[keyIndex + 1] : null;
const pathIndex = args.indexOf('--path');
const customPath = pathIndex !== -1 ? args[pathIndex + 1] : null;
const contentRootIndex = args.indexOf('--content-root');
if (args.includes('--git') && args.includes('--no-git')) failInitFlag('Choose --git or --no-git, not both.', jsonOutput);
if (args.includes('--db-only') && (contentRootIndex !== -1 || args.includes('--git'))) failInitFlag('--db-only cannot be combined with --content-root or --git.', jsonOutput);
const content: SharedContentOptions = {
...(contentRootIndex !== -1 ? { root: args[contentRootIndex + 1] } : {}),
dbOnly: args.includes('--db-only'), git: args.includes('--git') ? 'init' : 'none',
fresh: fileState.kind === 'absent',
};
// v0.42 (T17): pack selection on fresh installs. New brains default to
// gbrain-base-v2 (the 15-type canonical taxonomy); --schema-pack
// gbrain-base opts back to the legacy 24-type pack for users who don't
// want the new taxonomy on day one. Existing brains stay on whatever
// schema_pack their config.json already says.
const schemaPackIdx = args.indexOf('--schema-pack');
const schemaPack = schemaPackIdx !== -1 && args[schemaPackIdx + 1]
? args[schemaPackIdx + 1]
: (fileState.kind === 'present' ? fileState.config.schema_pack : undefined) ?? 'gbrain-base-v2';
// Multi-topology v1: thin-client init. Skips local engine entirely; writes
// remote_mcp config that the CLI dispatch guard reads to refuse DB-bound ops.
if (isMcpOnly) {
return initRemoteMcp({ args, jsonOutput, isForce, isNonInteractive });
}
// Re-run guard (A8): if thin-client config is already present, refuse to
// create a local engine without --force. Catches the scripted-setup-loop
// friction (running setup-gbrain repeatedly on a thin-client machine).
const existing = loadConfigFileOnly();
if (isThinClient(existing) && !isForce && !isMigrateOnly) {
const url = existing!.remote_mcp!.mcp_url;
const msg = `Thin-client config already present at ${configPath()} (remote_mcp.mcp_url=${url}).\n` +
`Re-init would create a local engine and conflict with the remote MCP setup.\n` +
`Use --force to overwrite, or \`gbrain init --mcp-only --force\` to refresh thin-client config.`;
if (jsonOutput) process.exit(initJsonError({ status: 'error', reason: 'thin_client_config_present', mcp_url: url, message: msg }, 'config_error', msg,
'Pass --force to overwrite, or run `gbrain init --mcp-only --force` to refresh the thin-client config.'));
console.error(msg);
process.exit(1);
}
// Schema-only path: apply initSchema against the already-configured engine
// without ever calling saveConfig. Used by apply-migrations, the stopgap
// script, and older releases' postinstall hook. Bare `gbrain init` defaults to PGLite
// and overwrites any existing Postgres config — we must never take that
// branch from a migration orchestrator.
//
// IMPORTANT: this short-circuit MUST run BEFORE resolveAIOptions() so
// migrate-only callers (which already have a configured brain) don't
// trigger env-detection / picker / fail-loud paths designed for fresh
// installs.
if (isMigrateOnly) {
return initMigrateOnly({ jsonOutput });
}
// v0.14: AI provider selection.
// --embedding-model PROVIDER:MODEL (verbose) or --model PROVIDER (shorthand, picks recipe default)
const embModelIdx = args.indexOf('--embedding-model');
const modelShortIdx = args.indexOf('--model');
const embDimsIdx = args.indexOf('--embedding-dimensions');
const expModelIdx = args.indexOf('--expansion-model');
// v0.27: --chat-model PROVIDER:MODEL — default subagent driver.
const chatModelIdx = args.indexOf('--chat-model');
// v0.37 (D9): --no-embedding opts into deferred-setup mode (D9 escape hatch).
const noEmbedding = args.includes('--no-embedding');
// v0.42 (#1780 Gap 2): --skip-embed-check bypasses the init-time embedding
// key validation (also honored via GBRAIN_INIT_SKIP_EMBED_CHECK=1).
const skipEmbedCheck = args.includes('--skip-embed-check');
const aiOpts = await resolveAIOptions({
verbose: embModelIdx !== -1 ? args[embModelIdx + 1] : null,
shorthand: modelShortIdx !== -1 ? args[modelShortIdx + 1] : null,
dimsArg: embDimsIdx !== -1 ? parseInt(args[embDimsIdx + 1], 10) : null,
expansion: expModelIdx !== -1 ? args[expModelIdx + 1] : null,
chat: chatModelIdx !== -1 ? args[chatModelIdx + 1] : null,
noEmbedding,
nonInteractive: isNonInteractive,
});
// db-availability loop (5a): Postgres-first ladder for agent-harness
// installs. Explicit opt-in flag — the zero-config `gbrain init` default
// stays PGLite (owner decision; the preference lives in the plugin lane).
if (args.includes('--prefer-postgres')) {
const { runPreferPostgresLadder } = await import('./init-prefer-postgres.ts');
return runPreferPostgresLadder({
jsonOutput,
apiKey,
customPath,
aiOpts,
schemaPack,
skipEmbedCheck,
content,
allowDocker: args.includes('--allow-docker'),
allowCreateDb: args.includes('--allow-create-db'),
localPostgres: args.includes('--local-postgres'),
});
}
// #3753: a --force re-init with NO explicit engine choice preserves the
// configured engine — the D5 persisted-config-wins rule extended to the
// engine field. Pre-fix, the PGLite default branch below swallowed a
// postgres config: following the deferred-setup hint verbatim
// (`gbrain init --force --embedding-model ...`) silently rewrote
// config.json to engine=pglite, orphaning the postgres data behind a
// config that no longer pointed at it. Switching engines stays available
// by saying so (--pglite / --supabase / --url). loadConfigFileOnly, NOT
// loadConfig: a transient env DATABASE_URL must not count as a configured
// engine here (CDX2-7); the env plane keeps its existing precedence in
// the non-interactive branch below.
let preservedPostgresUrl: string | null = null;
if (isForce && !isPGLite && !isSupabase && !manualUrl) {
const fileCfg = loadConfigFileOnly();
if (fileCfg?.engine === 'postgres' && fileCfg.database_url) {
preservedPostgresUrl = fileCfg.database_url;
console.error('[init] Existing postgres engine preserved (pass --pglite to switch engines).');
}
}
// Explicit PGLite mode
if (!preservedPostgresUrl && (isPGLite || (!isSupabase && !manualUrl && !isNonInteractive))) {
// Smart detection: scan for .md files unless --pglite flag forces it
if (!isPGLite && !isSupabase) {
const fileCount = countMarkdownFiles(process.cwd());
if (fileCount >= 1000) {
console.log(`Found ~${fileCount} .md files. For a brain this size, Supabase gives faster`);
console.log('search and remote access ($25/mo). PGLite works too but search will be slower at scale.');
console.log('');
console.log(' gbrain init --supabase Set up with Supabase (recommended for large brains)');
console.log(' gbrain init --pglite Use local PGLite anyway');
console.log('');
// Default to PGLite, let the user choose Supabase if they want
}
}
return initPGLite({ jsonOutput, apiKey, customPath, aiOpts, schemaPack, skipEmbedCheck, content });
}
// Supabase/Postgres mode
let databaseUrl: string;
if (manualUrl) {
databaseUrl = manualUrl;
} else if (isNonInteractive) {
// effectiveEnvDatabaseUrl applies the #427 guard: a DATABASE_URL that Bun
// auto-loaded from a .env in cwd must not seed a brain config — that is
// the "init inside a web-app checkout writes the app's DB into
// ~/.gbrain/config.json" failure mode.
const envUrl = effectiveEnvDatabaseUrl();
if (envUrl) {
databaseUrl = envUrl;
} else if (preservedPostgresUrl) {
databaseUrl = preservedPostgresUrl;
} else {
console.error('--non-interactive requires --url <connection_string> or GBRAIN_DATABASE_URL env var');
process.exit(1);
}
} else if (preservedPostgresUrl) {
databaseUrl = preservedPostgresUrl;
} else {
databaseUrl = await supabaseWizard();
}
return initPostgres({ databaseUrl, jsonOutput, apiKey, aiOpts, schemaPack, skipEmbedCheck, content });
}
const INIT_BOOLEAN_FLAGS = new Set([
'--pglite',
'--supabase',
'--mcp-only',
'--force',
'--non-interactive',
'--migrate-only',
'--json',
'--no-embedding',
'--skip-embed-check',
'--db-only',
'--git',
'--no-git',
// db-availability loop (5a): Postgres-first ladder for harness installs.
'--prefer-postgres',
'--allow-docker',
'--allow-create-db',
'--local-postgres',
]);
const INIT_VALUE_FLAGS = new Set([
'--url',
'--key',
'--path',
'--content-root',
'--schema-pack',
'--embedding-model',
'--model',
'--embedding-dimensions',
'--expansion-model',
'--chat-model',
'--mcp-url',
'--issuer-url',
'--oauth-client-id',
'--oauth-client-secret',
'--surface',
'--search-mode',
]);
function validateInitFlags(args: string[]) {
for (let i = 0; i < args.length; i++) {
const arg = args[i];
if (!arg.startsWith('-')) continue;
if (INIT_BOOLEAN_FLAGS.has(arg)) continue;
if (INIT_VALUE_FLAGS.has(arg)) {
if (i + 1 >= args.length || args[i + 1].startsWith('-')) {
failInitFlag(`gbrain init: ${arg} requires a value`, args.includes('--json'));
}
i += 1;
continue;
}
if (arg.startsWith('--')) {
failInitFlag(`gbrain init: unknown flag ${arg}`, args.includes('--json'));
}
}
}
function failInitFlag(message: string, jsonOutput: boolean): never {
if (jsonOutput) process.exit(initJsonError({ status: 'error', reason: 'invalid_flag', message }, 'invalid_params', message, 'Run `gbrain init --help` for supported flags.'));
console.error(message);
console.error('Run `gbrain init --help` for supported flags.');
process.exit(exitCodeForCode('invalid_params'));
}
interface ResolveAIOptionsArgs {
verbose: string | null; // --embedding-model
shorthand: string | null; // --model
dimsArg: number | null; // --embedding-dimensions
expansion: string | null; // --expansion-model
chat: string | null; // --chat-model
noEmbedding: boolean; // --no-embedding (D9)
nonInteractive: boolean; // --non-interactive (forces D3 fail-loud, no picker)
}
export interface ResolvedAIOptions {
embedding_model?: string;
embedding_dimensions?: number;
expansion_model?: string;
chat_model?: string;
/** v0.37 (D9): user opted into deferred embedding setup. */
noEmbedding?: boolean;
/** GBRA-248: noEmbedding came from the no-provider-key fallback, not a choice (init-embedding-plane.ts). */
implicitKeyless?: 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`.
*
* Precedence (per touchpoint, top wins):
* 1. Explicit flag (--embedding-model / --expansion-model / --chat-model)
* 2. Shorthand flag (--model PROVIDER) for embedding only
* 3. Env detection: walk env-ready recipes, group by provider id (D1-D4, D10).
* - Exactly one provider ready AND has the touchpoint → auto-pick + stderr notice.
* - Multiple ready → for embedding: TTY → picker (D1), non-TTY → fail loud (D3).
* For chat/expansion: leave default (gateway falls back at call time, D10).
* - Zero ready → for embedding: TTY → picker offers env-ready recipes
* OR setup hint with typo detection (D13); non-TTY → fail loud (D3).
*
* --no-embedding (D9) opt-in: skips embedding tier resolution entirely;
* persists nulls; embed callsites refuse with a config-set hint.
*/
async function resolveAIOptions(opts: ResolveAIOptionsArgs): Promise<ResolvedAIOptions> {
const { verbose, shorthand, dimsArg, expansion, chat, noEmbedding, nonInteractive } = opts;
const out: ResolvedAIOptions = {};
// --- D5: persisted config wins on re-init -----------------------------------
// When `~/.gbrain/config.json` already has embedding_model set (a re-init
// against an existing brain), honor it BEFORE env detection. Without this
// the env-detection branch fires unnecessarily on every re-init, and a
// non-TTY re-init with no env keys exits 1 (D3) even though the brain is
// already correctly configured. Caught by CI's E2E init sequence where
// multiple tests share `~/.gbrain` and only the first init has flags.
//
// The deferred-setup sentinel (`embedding_disabled: true`) is also honored —
// a re-init without --no-embedding shouldn't re-trigger fail-loud when the
// user already opted into deferred mode.
try {
const { loadConfig } = await import('../core/config.ts');
// #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 threw — treat as first-time install, fall through to env
// detection.
}
// --- Tier 1+2: explicit flags ---------------------------------------------
if (verbose) {
out.embedding_model = verbose;
// v0.46.3: an EXPLICIT --embedding-model wins over a seeded deferred-setup
// sentinel — without this, `gbrain init --force --embedding-model
// voyage:voyage-4` on a keyless brain (embedding_disabled persisted) would
// silently re-persist embedding_disabled and the documented recovery
// command would be a no-op. (--no-embedding is parsed later and still
// wins when both flags are passed.)
delete out.noEmbedding;
} else if (shorthand) {
const { getRecipe } = await import('../core/ai/recipes/index.ts');
const recipe = getRecipe(shorthand);
if (!recipe) {
console.error(`Unknown provider: ${shorthand}. Run \`gbrain providers list\` to see known providers.`);
process.exit(1);
}
// v0.32 D8=A: recipes flagged user_provided_models (litellm, llama-server)
// refuse implicit "first model" pick with a setup hint pointing the user
// at the explicit form. The shorthand --model is meaningless for these
// recipes because there's no canonical first model.
if (recipe.touchpoints.embedding?.user_provided_models === true) {
console.error(
`Provider ${shorthand} requires you to specify the model + dimensions explicitly:\n` +
` gbrain init --embedding-model ${shorthand}:<your-model-id> --embedding-dimensions <N>\n` +
(recipe.setup_hint ? `\nSetup: ${recipe.setup_hint}` : '')
);
process.exit(1);
}
// v0.46.3: the shorthand resolves the recipe's canonical model, not array
// position — Voyage lists voyage-4-large first but its canonical default
// is voyage-4 (see EmbeddingTouchpoint.default_model).
const canonicalModel =
recipe.touchpoints.embedding?.default_model ?? recipe.touchpoints.embedding?.models[0];
if (!canonicalModel) {
console.error(`Provider ${shorthand} has no embedding models listed. Use --embedding-model provider:model.`);
process.exit(1);
}
out.embedding_model = `${shorthand}:${canonicalModel}`;
// v0.46.3: explicit flag wins over a seeded deferred-setup sentinel (see the
// verbose branch above).
delete out.noEmbedding;
// #2051: width follows the model actually chosen, not the recipe default.
const { embeddingDimsForModel } = await import('../core/ai/model-resolver.ts');
out.embedding_dimensions = embeddingDimsForModel(recipe, canonicalModel);
}
if (dimsArg !== null && !Number.isNaN(dimsArg) && dimsArg > 0) {
out.embedding_dimensions = dimsArg;
} else if (out.embedding_model && out.embedding_dimensions === undefined) {
// Derive default dims from the resolved recipe when verbose form was used.
const { getRecipe } = await import('../core/ai/recipes/index.ts');
const providerId = out.embedding_model.split(':')[0];
const recipe = getRecipe(providerId);
// v0.32: user_provided_models recipes (litellm, llama-server) have
// default_dims=0 and ship with `models: []` — there's no sensible
// fallback. Refuse explicitly here too. Without this, the verbose path
// `--embedding-model llama-server:foo` (no --embedding-dimensions) would
// fall through to configureGateway's default (1536), creating a
// wrong-width schema that explodes only at first embed.
if (recipe?.touchpoints.embedding?.user_provided_models === true) {
console.error(
`Provider ${providerId} requires --embedding-dimensions <N> when using --embedding-model ${out.embedding_model}.\n` +
`User-driven-model recipes (litellm, llama-server) have no default dimension.\n` +
(recipe.setup_hint ? `\nSetup: ${recipe.setup_hint}` : '')
);
process.exit(1);
}
// #2051: resolve the width from the SPECIFIC model, not the recipe-wide
// default. `--embedding-model ollama:bge-m3` must yield 1024, not Ollama's
// nomic-shaped 768.
if (recipe) {
const { embeddingDimsForModel } = await import('../core/ai/model-resolver.ts');
const dims = embeddingDimsForModel(recipe, out.embedding_model);
if (dims > 0) out.embedding_dimensions = dims;
}
}
if (expansion) out.expansion_model = expansion;
if (chat) out.chat_model = chat;
// --- D9: --no-embedding opt-in --------------------------------------------
// Even when other flags were passed, --no-embedding signals "skip embedding
// configuration entirely". Persist the explicit opt-in (T6/T7 use it).
if (noEmbedding) {
out.noEmbedding = true;
// Wipe any tentative embedding settings — opt-in means truly nothing.
delete out.embedding_model;
delete out.embedding_dimensions;
}
// --- Tier 3: env detection ------------------------------------------------
// Fires per touchpoint, only when no explicit flag was passed for that
// tier. Embedding is the critical path (column width); chat/expansion are
// best-effort (gateway falls back gracefully at call time, D10).
if (!out.noEmbedding && !out.embedding_model) {
await resolveEmbeddingByEnv(out, nonInteractive);
}
if (!out.expansion_model) {
await resolveExpansionByEnv(out);
}
if (!out.chat_model) {
await resolveChatByEnv(out);
}
return out;
}
// ============================================================================
// v0.37 env-detection helpers (T5)
//
// These run when no explicit flag is passed for the corresponding touchpoint.
// They share `groupReadyByProvider` so the per-touchpoint surface stays
// consistent (codex finding #2: group by provider id, not by recipe, so two
// recipes sharing OPENAI_API_KEY can't double-count).
// ============================================================================
interface ReadyProvider {
recipeId: string;
recipe: import('../core/ai/types.ts').Recipe;
}
/**
* Walk recipes and return providers env-ready for the given touchpoint.
* Exported for unit tests (parameterizable via env arg).
*
* Excludes local-only providers (no auth_env.required, e.g. Ollama,
* llama-server) from auto-pick UNLESS they're the only thing available.
* Picking Ollama silently when the user has OPENAI_API_KEY set is a
* silent-broken-state class (Ollama daemon may not be running, or the
* user clearly intended a hosted provider). Local-only providers stay
* accessible via explicit `--embedding-model ollama:...`.
*/
export async function groupReadyByProvider(
touchpoint: 'embedding' | 'expansion' | 'chat',
env: NodeJS.ProcessEnv = process.env,
): Promise<ReadyProvider[]> {
const { listRecipes } = await import('../core/ai/recipes/index.ts');
const { envReady } = await import('./providers.ts');
const ready: ReadyProvider[] = [];
const seen = new Set<string>();
for (const r of listRecipes()) {
if (seen.has(r.id)) continue;
const tp = r.touchpoints[touchpoint];
if (!tp) continue;
// Skip recipes that ship without any models (user_provided_models flag,
// e.g. litellm-proxy, llama-server). The shorthand --model path errors
// for these; auto-pick should too.
const tpModels = (tp as { models?: string[] }).models;
if (!Array.isArray(tpModels) || tpModels.length === 0) continue;
// Skip recipes whose user_provided_models flag is set even when models[]
// has entries (defensive — shouldn't happen but cheap).
if ((tp as { user_provided_models?: boolean }).user_provided_models) continue;
// Skip local-only providers (no auth required) from auto-pick. They're
// still picker-selectable explicitly, but silent auto-pick is wrong UX.
const required = r.auth_env?.required ?? [];
if (required.length === 0) continue;
if (envReady(r, env)) {
ready.push({ recipeId: r.id, recipe: r });
seen.add(r.id);
}
}
return ready;
}
/** Look at env-vars the user set that look like typos of recipe-required keys.
* Exported for unit tests (parameterizable via env arg). */
export async function findEnvKeyTypos(
env: NodeJS.ProcessEnv = process.env,
): Promise<Array<{ userSet: string; suggested: string }>> {
const { suggestNearest } = await import('../core/levenshtein.ts');
const { listRecipes } = await import('../core/ai/recipes/index.ts');
// Build the canonical name set from every recipe's auth_env.required.
const canonical = new Set<string>();
for (const r of listRecipes()) {
for (const k of r.auth_env?.required ?? []) canonical.add(k);
}
const out: Array<{ userSet: string; suggested: string }> = [];
// Walk user env vars that look API-key-shaped to keep the suggestion noise low.
const KEY_SHAPE = /^[A-Z][A-Z0-9_]*_(API_)?KEY$/;
for (const userKey of Object.keys(env)) {
if (!KEY_SHAPE.test(userKey)) continue;
if (canonical.has(userKey)) continue; // exact match, not a typo
if (!env[userKey]) continue; // empty string, skip
const suggestion = suggestNearest(userKey, [...canonical], /* maxDistance */ 3);
if (suggestion && suggestion !== userKey) {
// False-positive guard (per plan D13): suggested canonical not ALSO set.
if (!env[suggestion]) {
out.push({ userSet: userKey, suggested: suggestion });
}
}
}
return out;
}
/** Emit the "no embedding provider" message + paste-ready setup. Keyless
* continue leads (it always works); key setup follows for the upgrade. */
function printNoEmbeddingProviderHint(typos: Array<{ userSet: string; suggested: string }>): void {
console.error('\nNo embedding provider configured.');
console.error('Continue without one (keyless — keyword search + memory your agent writes):');
console.error(' gbrain init --pglite --no-embedding');
console.error(' (enable semantic search later by re-running with a key:');
console.error(' gbrain init --force --pglite --embedding-model <id>)');
console.error('');
console.error('Or set a key to upgrade capabilities:');
console.error(' export VOYAGE_API_KEY=pa-… # semantic search (voyage:voyage-4, 1024d) — default');
console.error(' export OPENAI_API_KEY=sk-… # semantic search (1536d) + automatic fact extraction');
console.error(' export ANTHROPIC_API_KEY=sk-ant-… # automatic fact extraction (no embeddings API)');
console.error('Then re-run: gbrain init --pglite');
console.error('');
console.error('Or pick explicitly:');
console.error(' gbrain init --pglite --embedding-model voyage:voyage-4');
// D13: surface near-miss env vars (e.g. OPENAPI_API_KEY → OPENAI_API_KEY).
if (typos.length > 0) {
console.error('');
for (const t of typos) {
console.error(`Note: detected ${t.userSet}; did you mean ${t.suggested}?`);
}
}
}
async function writeNewInstallRerankerDefault(
engine: { getConfig(key: string): Promise<string | null>; setConfig(key: string, value: string): Promise<void> },
resolvedModel: string | undefined,
): Promise<void> {
try {
// Never-clobber: an existing explicit reranker model OR enabled override
// means the user already decided — leave both keys alone.
const [existingModel, existingEnabled] = await Promise.all([
engine.getConfig('search.reranker.model'),
engine.getConfig('search.reranker.enabled'),
]);
if (existingModel || existingEnabled != null) return;
const { DEFAULT_RERANKER_MODEL } = await import('../core/ai/defaults.ts');
const { rerankerReadiness } = await import('../core/ai/reranker-readiness.ts');
const { mergedProviderEnv } = await import('../core/ai/provider-env.ts');
// Same plane the CLI hands the gateway: env > file > DB-plane provider keys
// (a `--force` re-init of a brain whose Voyage key lives only in the config
// table must not be classified keyless and locked into `enabled=false`).
const fileCfg = loadConfigFileOnly();
let mergedCfg = fileCfg;
try {
const { loadConfigWithEngine } = await import('../core/config.ts');
mergedCfg = await loadConfigWithEngine(engine as any, fileCfg);
} catch { mergedCfg = fileCfg; }
const readiness = rerankerReadiness(DEFAULT_RERANKER_MODEL, mergedProviderEnv(mergedCfg, process.env));
if (readiness.ready) {
// Nothing to write: the bundle default already resolves to it.
console.log(
` Reranker: ${DEFAULT_RERANKER_MODEL} (mode-bundle default` +
`${readiness.requiredKey ? `; same ${readiness.requiredKey}` : ''})`,
);
return;
}
if (resolvedModel) {
const key = readiness.requiredKey ?? 'VOYAGE_API_KEY';
await engine.setConfig('search.reranker.enabled', 'false');
console.log(
` Reranker: disabled (no ${key} — enable later: export ${key}=… && ` +
'gbrain config set search.reranker.enabled true)',
);
}
} catch {
// Cosmetic; never block init.
}
}
/** Loud keyless-continue notice for the no-keys default path. The upgrade
* command is `init --force` re-init, NOT `config set embedding_model` — that
* key is a schema-sizing file-plane field that `gbrain config set` refuses
* (it would be a silent no-op), so pointing users there is a dead end. */
function printKeylessContinueNotice(): void {
console.error(
'No provider keys detected — continuing in keyless mode:\n' +
' keyword search + memory your agent writes down itself. Everything works.\n' +
' One optional key upgrades capabilities — OpenAI: semantic search + automatic\n' +
' fact extraction; Voyage: semantic search; Anthropic: fact extraction.\n' +
' Fact extraction activates as soon as the key is set (no re-init); semantic\n' +
' search needs a re-run:\n' +
' `gbrain init --force --pglite --embedding-model <id>` (re-imports via `gbrain sync`).',
);
}
async function resolveEmbeddingByEnv(out: ResolvedAIOptions, nonInteractive: boolean): Promise<void> {
// v0.46.3: provider readiness folds FILE-PLANE keys too (docs explicitly
// permit `voyage_api_key` etc. in ~/.gbrain/config.json) — env still wins
// via buildGatewayConfig's spread order. Without this, a non-interactive
// fresh install keyed only via config.json reported zero providers and
// silently persisted keyless mode.
const fileCfgForKeys = loadConfigFileOnly();
let effectiveEnv: NodeJS.ProcessEnv = process.env;
if (fileCfgForKeys) {
try {
const { buildGatewayConfig } = await import('../core/ai/build-gateway-config.ts');
effectiveEnv = buildGatewayConfig(fileCfgForKeys).env as NodeJS.ProcessEnv;
} catch {
// Fold failure → env-only readiness (pre-v0.46.3 behavior).
}
}
const ready = await groupReadyByProvider('embedding', effectiveEnv);
const isTTY = !nonInteractive && !!process.stdin.isTTY;
if (ready.length === 1) {
const r = ready[0].recipe;
const tp = r.touchpoints.embedding!;
if (Array.isArray(tp.models) && tp.models.length > 0) {
// v0.46.3: recipes carry a canonical default_model — array order is
// quality-sorted, not recommendation-sorted (Voyage lists voyage-4-large
// first; the canonical pick is voyage-4).
const model = tp.default_model ?? tp.models[0];
const fullModel = `${r.id}:${model}`;
// When the resolved provider matches the NEW-INSTALL canonical default
// model, use NEW_INSTALL_DEFAULT_EMBEDDING_DIMENSIONS instead of the
// recipe's `default_dims` so fresh-install schema width stays aligned
// with the system default (1024 for voyage-4).
const { NEW_INSTALL_DEFAULT_EMBEDDING_MODEL, NEW_INSTALL_DEFAULT_EMBEDDING_DIMENSIONS } =
await import('../core/ai/defaults.ts');
const { embeddingDimsForModel } = await import('../core/ai/model-resolver.ts');
// #2051: non-canonical models resolve per-model, not recipe-wide.
const dims = fullModel === NEW_INSTALL_DEFAULT_EMBEDDING_MODEL
? NEW_INSTALL_DEFAULT_EMBEDDING_DIMENSIONS
: embeddingDimsForModel(r, model);
out.embedding_model = fullModel;
out.embedding_dimensions = dims;
console.error(
`Detected ${r.auth_env?.required?.[0] ?? r.id} env var. ` +
`Using ${fullModel} (${dims}d). ` +
`Override with --embedding-model.`,
);
return;
}
}
// Zero keys — keyless is a first-class posture (the whole paste-in
// bootstrap runs on it), so the DEFAULT is to continue keyless with a loud
// notice, not exit 1. Fail-loud survives in exactly one zero-key case: a
// near-miss env var (OPENAPI_API_KEY → OPENAI_API_KEY) signals the user
// MEANT to configure a key — completing keyless there would silently bury
// their typo.
if (ready.length === 0) {
const typos = await findEnvKeyTypos();
if (typos.length > 0) {
printNoEmbeddingProviderHint(typos);
process.exit(1);
}
if (!isTTY) {
printKeylessContinueNotice();
out.noEmbedding = out.implicitKeyless = true;
return;
}
// TTY → picker (local providers like ollama may be selectable); a null
// pick (nothing offered, user skipped, or EOF) continues keyless.
const { pickProvider } = await import('./init-provider-picker.ts');
const picked = await pickProvider({ touchpoint: 'embedding', env: effectiveEnv, isTTY: true });
if (!picked) {
printKeylessContinueNotice();
out.noEmbedding = out.implicitKeyless = true;
return;
}
out.embedding_model = picked.fullModel;
out.embedding_dimensions = picked.dim;
return;
}
// ready.length > 1 — picker (TTY); non-TTY auto-picks the canonical default
// when its key is present (the most common agent/dev setup is 2+ provider
// keys — failing there blocked scripted installs), else fail-loud per D2/D3
// (a genuinely ambiguous set with no canonical candidate stays explicit).
if (!isTTY) {
const { NEW_INSTALL_DEFAULT_EMBEDDING_MODEL, NEW_INSTALL_DEFAULT_EMBEDDING_DIMENSIONS } =
await import('../core/ai/defaults.ts');
const canonicalProvider = NEW_INSTALL_DEFAULT_EMBEDDING_MODEL.split(':')[0];
const canonical = ready.find((p) => p.recipeId === canonicalProvider);
if (canonical) {
out.embedding_model = NEW_INSTALL_DEFAULT_EMBEDDING_MODEL;
out.embedding_dimensions = NEW_INSTALL_DEFAULT_EMBEDDING_DIMENSIONS;
console.error(
`Multiple embedding providers env-ready (${ready.map(p => p.recipeId).join(', ')}). ` +
`Using the default ${NEW_INSTALL_DEFAULT_EMBEDDING_MODEL} (${NEW_INSTALL_DEFAULT_EMBEDDING_DIMENSIONS}d). ` +
`Override with --embedding-model.`,
);
return;
}
console.error(`Multiple embedding providers env-ready: ${ready.map(p => p.recipeId).join(', ')}.`);
console.error(`Disambiguate by passing --embedding-model <provider>:<model>, or unset extra env vars.`);
process.exit(1);
}
const { pickProvider } = await import('./init-provider-picker.ts');
const picked = await pickProvider({ touchpoint: 'embedding', env: effectiveEnv, isTTY: true });
if (!picked) {
// The embedding picker offers an explicit "0) none — continue keyless"
// option (and returns null on it). Honor that instead of aborting: a user
// with multiple keys who deliberately chose keyless gets keyless, matching
// the zero-key path. (Ctrl-D / EOF / invalid also land here → keyless.)
printKeylessContinueNotice();
out.noEmbedding = true;
return;
}
out.embedding_model = picked.fullModel;
out.embedding_dimensions = picked.dim;
}
async function resolveExpansionByEnv(out: ResolvedAIOptions): Promise<void> {
const ready = await groupReadyByProvider('expansion');
// Per D10: chat/expansion fall through to gateway default when ambiguous.
if (ready.length === 1) {
const r = ready[0].recipe;
const tp = r.touchpoints.expansion!;
if (Array.isArray(tp.models) && tp.models.length > 0) {
out.expansion_model = `${r.id}:${tp.models[0]}`;
console.error(`Detected ${r.auth_env?.required?.[0] ?? r.id} env var. Using ${out.expansion_model} for expansion.`);
}
}
// 0 or >1 → silent: gateway default (`anthropic:claude-haiku-4-5-…`) wins
// and falls back gracefully at call time when key isn't set.
}
/** @internal exported for tests — pins the no-persist contract (key-aware
* runtime resolution replaced install-time chat_model pins). */
export async function resolveChatByEnv(out: ResolvedAIOptions): Promise<void> {
const ready = await groupReadyByProvider('chat');
if (ready.length === 1) {
const r = ready[0].recipe;
const tp = r.touchpoints.chat!;
if (Array.isArray(tp.models) && tp.models.length > 0) {
// Deliberately does NOT write out.chat_model: key-aware tier defaults
// (model-config.ts resolveTierDefault + resolveEffectiveChatModel)
// route chat/extraction to this provider at runtime, and a persisted
// install-time pin freezes the provider choice — it goes stale the
// moment the user switches keys. Detection stays for the init summary;
// the displayed model is the same resolution the runtime will use
// (discovered-latest for OpenAI, recipe entry otherwise).
const { resolveTierDefault } = await import('../core/model-config.ts');
const effective = resolveTierDefault('reasoning');
const shown = effective.startsWith(`${r.id}:`) ? effective : `${r.id}:${tp.models[0]}`;
console.error(
`Detected ${r.auth_env?.required?.[0] ?? r.id} env var. Chat + fact extraction will use ` +
`${shown} (key-aware default; nothing written to config).`,
);
}
}
// 0 or >1 → silent: the key-aware tier default wins at runtime.
// The subagent enforcement at minions/queue.ts already routes subagent jobs
// via classifyCapabilities regardless of the chat_model setting.
}
/**
* Apply the schema against the already-configured engine. No saveConfig.
* No PGLite fallback when no config exists. Used by migration orchestrators
* to bump an existing brain's schema to the latest version without
* clobbering the user's chosen engine.
*/
async function initMigrateOnly(opts: { jsonOutput: boolean }) {
// v0.41.37.0 #1605: delegate to the shared runMigrateOnlyCore so the CLI path
// and the in-process migration-orchestrator path can't drift (single source
// of truth for configureGateway-before-initSchema + the schema bring-up).
const { runMigrateOnlyCore, MigrateOnlyError } = await import('./migrations/in-process.ts');
try {
const result = await runMigrateOnlyCore();
if (opts.jsonOutput) {
setInitJsonResult({ status: 'success', engine: result.engine, mode: 'migrate-only' });
} else {
console.log(`Schema up to date (engine: ${result.engine}).`);
}
} catch (e) {
// Preserve the CLI's shared retryable busy envelope for migration callers.
if (e instanceof PgliteBusyError || (e as { code?: unknown }).code === 'client_behind') throw e;
const isNoConfig = e instanceof MigrateOnlyError && e.message.startsWith('No brain configured');
const msg = e instanceof Error ? e.message : String(e);
if (opts.jsonOutput) process.exit(initJsonError({ status: 'error', reason: isNoConfig ? 'no_config' : 'migrate_failed', message: msg },
isNoConfig ? 'no_brain' : 'database_error', msg, isNoConfig ? 'Run `gbrain init --pglite --no-embedding` first.' : 'Run `gbrain doctor --json` to see what blocks the schema bring-up.'));
console.error(msg);
process.exit(1);
}
}
/**
* `gbrain init --mcp-only` — thin-client setup. Writes a `remote_mcp` config
* field, runs three pre-flight smokes (OAuth discovery, token round-trip,
* MCP initialize), and never creates a local engine.
*
* Required flags (or env vars):
* --issuer-url <url> (or GBRAIN_REMOTE_ISSUER_URL)
* --mcp-url <url> (or GBRAIN_REMOTE_MCP_URL)
* --oauth-client-id <id> (or GBRAIN_REMOTE_CLIENT_ID)
* --oauth-client-secret <s> (or GBRAIN_REMOTE_CLIENT_SECRET; preferred)
*
* Re-run semantics: if a thin-client config already exists, --force overwrites;
* otherwise refuses with a hint pointing at the existing mcp_url.
*/
async function initRemoteMcp(opts: {
args: string[];
jsonOutput: boolean;
isForce: boolean;
isNonInteractive: boolean;
}) {
const { args, jsonOutput, isForce } = opts;
const arg = (flag: string) => {
const i = args.indexOf(flag);
return i !== -1 ? args[i + 1] : null;
};
const issuerUrl = (arg('--issuer-url') ?? process.env.GBRAIN_REMOTE_ISSUER_URL ?? '').trim();
const mcpUrl = (arg('--mcp-url') ?? process.env.GBRAIN_REMOTE_MCP_URL ?? '').trim();
const clientId = (arg('--oauth-client-id') ?? process.env.GBRAIN_REMOTE_CLIENT_ID ?? '').trim();
const clientSecret = (arg('--oauth-client-secret') ?? process.env.GBRAIN_REMOTE_CLIENT_SECRET ?? '').trim();
function fail(reason: string, message: string, extra: Record<string, unknown> = {}): never {
const code = reason.startsWith('missing_') ? 'invalid_params' : reason.startsWith('token_') ? 'invalid_token'
: reason.startsWith('discovery_') || reason.startsWith('mcp_smoke_') ? 'unavailable' : 'config_error';
if (jsonOutput) process.exit(initJsonError({ status: 'error', reason, message, ...extra }, code, message.split('\n')[0],
message.split('\n').slice(1).join(' ') || 'Run `gbrain init --help` for the thin-client flags.'));
console.error(message);
process.exit(code === 'invalid_params' ? exitCodeForCode(code) : 1);
}
if (!issuerUrl) fail('missing_issuer_url', '--issuer-url is required (or set GBRAIN_REMOTE_ISSUER_URL). Example: --issuer-url https://brain-host.local:3001');
if (!mcpUrl) fail('missing_mcp_url', '--mcp-url is required (or set GBRAIN_REMOTE_MCP_URL). Example: --mcp-url https://brain-host.local:3001/mcp');
if (!clientId) fail('missing_client_id', '--oauth-client-id is required (or set GBRAIN_REMOTE_CLIENT_ID). Get it from `gbrain auth register-client` on the host.');
if (!clientSecret) fail('missing_client_secret', '--oauth-client-secret is required (or set GBRAIN_REMOTE_CLIENT_SECRET). Get it from `gbrain auth register-client` on the host.');
const existing = inspectRemoteInitState(isForce, fail);
if (!jsonOutput) {
console.log('Thin-client setup — running pre-flight smoke...');
console.log(` issuer: ${issuerUrl}`);
console.log(` mcp: ${mcpUrl}`);
}
// 1. OAuth discovery
const disco = await discoverOAuth(issuerUrl);
if (!disco.ok) {
fail(
`discovery_${disco.reason}`,
`Pre-flight failed: OAuth discovery on ${issuerUrl} — ${disco.message}\n` +
`Hint: confirm the issuer_url, that the host is reachable, and that \`gbrain serve --http\` is running there.`,
{ detail: disco.message, ...(disco.status ? { status: disco.status } : {}) },
);
}
if (!jsonOutput) console.log(` ✓ OAuth discovery (token_endpoint=${disco.metadata.token_endpoint})`);
// 2. Token round-trip
const tokenRes = await mintClientCredentialsToken(disco.metadata.token_endpoint, clientId, clientSecret);
if (!tokenRes.ok) {
fail(
`token_${tokenRes.reason}`,
`Pre-flight failed: OAuth /token — ${tokenRes.message}\n` + (tokenRes.reason === 'rate_limited'
? `Hint: the host's /token mint budget is spent; rerun after the wait, or the host operator can raise GBRAIN_OAUTH_TOKEN_RATE_LIMIT_MAX.`
: `Hint: the host operator can run \`gbrain auth register-client <name> --grant-types client_credentials --scopes read,write,admin\` to mint fresh credentials.`),
{ detail: tokenRes.message, ...(tokenRes.status ? { status: tokenRes.status } : {}), ...(tokenRes.retry_after_s !== undefined ? { retry_after_s: tokenRes.retry_after_s } : {}) },
);
}
if (!jsonOutput) console.log(` ✓ OAuth /token (${tokenRes.token.token_type ?? 'bearer'}, scope=${tokenRes.token.scope ?? 'unspecified'})`);
// 3. MCP smoke
const mcpRes = await smokeTestMcp(mcpUrl, tokenRes.token.access_token);
if (!mcpRes.ok) {
fail(
`mcp_smoke_${mcpRes.reason}`,
`Pre-flight failed: MCP initialize on ${mcpUrl} — ${mcpRes.message}\n` +
`Hint: confirm \`mcp_url\` matches the path the host serves \`/mcp\` on (default: <issuer_url>/mcp).`,
{ detail: mcpRes.message, ...(mcpRes.status ? { status: mcpRes.status } : {}) },
);
}
if (!jsonOutput) console.log(` ✓ MCP initialize`);
// 4. Persist config. Preserve any existing AI/storage/etc. fields on
// the existing config — only overwrite remote_mcp + drop engine/database
// fields if this install is converting from local-engine to thin-client.
// For first-time setup, write a minimal config.
const baseConfig: Partial<GBrainConfig> = existing
? { ...existing, database_url: undefined, database_path: undefined }
: {};
// engine field is required on the type; leave it inferred to 'postgres'
// for default purposes — it's never used because the dispatch guard
// short-circuits any DB-bound path before connectEngine.
const config: GBrainConfig = {
...(baseConfig as GBrainConfig),
engine: existing?.engine ?? 'postgres',
remote_mcp: {
issuer_url: issuerUrl.replace(/\/+$/, ''),
mcp_url: mcpUrl,
oauth_client_id: clientId,
// Only persist the secret to disk if it didn't come from the env var.
// Env-var-supplied secrets stay in env; on-disk copy is opt-in via
// the --oauth-client-secret flag (or absent env var).
...(process.env.GBRAIN_REMOTE_CLIENT_SECRET === clientSecret
? {}
: { oauth_client_secret: clientSecret }),
},
};
// database_url / database_path get explicitly removed when converting; the
// spread above with `undefined` doesn't drop them in JSON, so prune.
const configRecord = config as unknown as Record<string, unknown>;
delete configRecord.database_url;
delete configRecord.database_path;
preserveConversionConfig(true);
saveConfig(config);
if (jsonOutput) {
setInitJsonResult({
status: 'success',
mode: 'thin-client',
issuer_url: config.remote_mcp!.issuer_url,
mcp_url: config.remote_mcp!.mcp_url,
oauth_client_id: config.remote_mcp!.oauth_client_id,
oauth_secret_in_config: 'oauth_client_secret' in config.remote_mcp!,
});
} else {
console.log('');
console.log('Thin-client mode configured. No local DB.');
console.log(` Config: ${configPath()}`);
console.log(` Talks to: ${config.remote_mcp!.mcp_url}`);
console.log('');
console.log('Next steps:');
console.log(` 1. Configure your agent's MCP client to point at ${config.remote_mcp!.mcp_url} (Claude Desktop / Hermes / openclaw).`);
console.log(' 2. Run `gbrain doctor` to re-verify connectivity at any time.');
console.log(' 3. Run `gbrain remote ping` after writing markdown if you want the host to re-index immediately (Tier B).');
}
}
async function configureGatewayWithMergedPrecedence(
aiOpts?: { embedding_model?: string; embedding_dimensions?: number; expansion_model?: string; chat_model?: string },
): Promise<{ embedding_model: string; embedding_dimensions: number; expansion_model: string; chat_model: string }> {
const existingFile = loadConfigFileOnly() ?? ({} as GBrainConfig);
// loadConfig() merges env on top of file — perfect for the gateway path,
// where env should win over a stale file. NOT used for the save path
// (see B.4), which uses loadConfigFileOnly so transient env state never
// pollutes config.json.
const envOverlay = loadConfig() ?? ({} as GBrainConfig);
const merged = {
embedding_model: aiOpts?.embedding_model ?? envOverlay.embedding_model ?? existingFile.embedding_model,
embedding_dimensions: aiOpts?.embedding_dimensions ?? envOverlay.embedding_dimensions ?? existingFile.embedding_dimensions,
expansion_model: aiOpts?.expansion_model ?? envOverlay.expansion_model ?? existingFile.expansion_model,
chat_model: aiOpts?.chat_model ?? envOverlay.chat_model ?? existingFile.chat_model,
};
const { configureGateway, getEmbeddingModel, getEmbeddingDimensions, getExpansionModel, getChatModel } = await import('../core/ai/gateway.ts');
configureGateway({
embedding_model: merged.embedding_model,
embedding_dimensions: merged.embedding_dimensions,
expansion_model: merged.expansion_model,
chat_model: merged.chat_model,
env: { ...process.env },
});
// Read back resolved values — gateway applies internal defaults for unset
// fields, so these are the values that actually shaped the schema.
return {
embedding_model: getEmbeddingModel(),
embedding_dimensions: getEmbeddingDimensions(),
expansion_model: getExpansionModel(),
chat_model: getChatModel(),
};
}
function printResolvedAIChoice(
resolved: { embedding_model: string; embedding_dimensions: number; expansion_model: string; chat_model: string },
aiOpts?: { embedding_model?: string },
) {
const explicit = aiOpts?.embedding_model != null;
const label = explicit ? '' : ' [default]';
console.log(` Embedding: ${resolved.embedding_model} (${resolved.embedding_dimensions}d)${label}`);
console.log(` Expansion: ${resolved.expansion_model}`);
console.log(` Chat: ${resolved.chat_model}`);
}
async function assertInitEmbeddingIdentity(engine: BrainEngine, model: string | undefined): Promise<void> {
if (!model) return;
const stored = await readStoredEmbeddingIdentity(engine);
if (stored?.model === model) return;
for (const table of await readPrimaryEmbeddingStores(engine)) {
const rows = await engine.executeRaw<{ present: boolean }>(
`SELECT EXISTS (SELECT 1 FROM ${table} WHERE embedding IS NOT NULL) AS present`,
);
if (rows[0]?.present) {
throw new Error('Existing vectors belong to a different or unrecorded embedding model. Re-initialization cannot change their identity, even at the same width. Run gbrain migrate embeddings --status and preview an explicit migration with --dry-run.');
}
}
}
export async function initPGLite(opts: {
jsonOutput: boolean;
apiKey: string | null;
customPath: string | null;
aiOpts?: ResolvedAIOptions;
/** v0.42 (T17): schema pack to default. Stored as config.schema_pack
* so loadActivePack's homeConfig tier resolves it. */
schemaPack?: string;
/** v0.42 (#1780 Gap 2): skip the init-time embedding-key validation. */
skipEmbedCheck?: boolean;
content?: SharedContentOptions;
}) {
const dbPath = opts.customPath || gbrainPath('brain.pglite');
console.log(`Setting up local brain with PGLite (no server needed)...`);
// v0.37.10.0 T6 (D11): preflight schema dim BEFORE any DB write or schema
// creation. After T5's env detection runs, opts.aiOpts has either an
// embedding_model resolved (auto-pick / picker / explicit flag) OR
// noEmbedding=true (D9 opt-in). Either way we MUST agree with the
// gateway's resolved dim by construction — preflight validates that.
let resolvedDim: number | undefined;
let resolvedModel: string | undefined;
if (opts.aiOpts?.noEmbedding) {
// D9 deferred-setup mode: skip preflight, no model/dim resolved.
if (!opts.aiOpts.implicitKeyless) console.log(deferredEmbeddingHint({ engine: 'pglite', database_path: dbPath, embedding_disabled: true }));
} else if (opts.aiOpts?.embedding_model) {
const { resolveSchemaEmbeddingDim } = await import('../core/embedding-dim-check.ts');
const pre = resolveSchemaEmbeddingDim({
embedding_model: opts.aiOpts.embedding_model,
embedding_dimensions: opts.aiOpts.embedding_dimensions,
});
if (!pre.ok) {
console.error(`\nRefusing to init: ${pre.error}\n`);
if (opts.jsonOutput) process.exit(initJsonError({ status: 'error', reason: 'preflight_failed', error: pre.error }, 'config_error', pre.error, INIT_EMBEDDING_HINT));
process.exit(1);
}
resolvedDim = pre.dim;
resolvedModel = pre.model;
}
// If neither --no-embedding nor an embedding_model is resolved, resolveAIOptions
// already exited 1 with the fail-loud setup hint (T5). Reaching here without
// either means we have a user-passed combination the previous step accepted —
// typically `--embedding-model` flag without env detection running.
// v0.37.10.0 T6 + v0.37.11.0 Lane B.1: ALWAYS configureGateway BEFORE
// initSchema. Schema substitution at pglite-schema.ts:833 and the runtime
// gateway share one source of truth. Resolution precedence locked in
// resolveAIOptions above: CLI flags > env vars > existing file > gateway
// defaults.
const { configureGateway } = await import('../core/ai/gateway.ts');
// v0.46.3: keyless fresh installs size the embedding column at the NEW-INSTALL
// width (1024), not the legacy configless fallback (1280) — the sizing is an
// explicit param here, NOT a rewire of the schema generators' legacy import
// (those also run on existing-brain reconnects, where legacy must stay
// legacy). Existing keyless brains are unaffected: initSchema never resizes
// an existing column, and the Lane B.5 mismatch guard stays off for keyless
// (resolvedDim is undefined).
const { NEW_INSTALL_DEFAULT_EMBEDDING_DIMENSIONS: newInstallDims } =
await import('../core/ai/defaults.ts');
if (resolvedModel) console.log(` Embedding: ${resolvedModel} (${resolvedDim}d)`);
if (opts.aiOpts?.expansion_model) console.log(` Expansion: ${opts.aiOpts.expansion_model}`);
if (opts.aiOpts?.chat_model) console.log(` Chat: ${opts.aiOpts.chat_model}`);
const engine = await createEngine({ engine: 'pglite' });
try {
await engine.connect({ database_path: dbPath, engine: 'pglite' });
const freshContentDatabase = await isNewContentDatabase(engine);
await assertInitEmbeddingIdentity(engine, resolvedModel);
const kept = await keptEmbeddingIdentity(engine, opts.aiOpts, freshContentDatabase);
if (opts.aiOpts?.implicitKeyless) console.log(kept ? keptEmbeddingNotice(kept) : deferredEmbeddingHint({ engine: 'pglite', database_path: dbPath, embedding_disabled: true }));
configureGateway({
embedding_model: resolvedModel ?? kept?.model ?? opts.aiOpts?.embedding_model,
embedding_dimensions: resolvedDim ?? kept?.dimensions ?? opts.aiOpts?.embedding_dimensions ??
(opts.aiOpts?.noEmbedding ? newInstallDims : undefined),
expansion_model: opts.aiOpts?.expansion_model,
chat_model: opts.aiOpts?.chat_model,
env: { ...process.env },
});
const embedCheck = await runInitEmbedCheck({
resolvedModel,
resolvedDim,
expansionModel: opts.aiOpts?.expansion_model,
chatModel: opts.aiOpts?.chat_model,
apiKey: opts.apiKey ?? undefined,
noEmbedding: opts.aiOpts?.noEmbedding,
skipFlag: opts.skipEmbedCheck,
});
if (resolvedDim) {
const { readContentChunksEmbeddingDim, embeddingMismatchMessage } = await import('../core/embedding-dim-check.ts');
const existing = await readContentChunksEmbeddingDim(engine);
if (existing.exists && existing.dims !== null && existing.dims !== resolvedDim) {
console.error('\n' + embeddingMismatchMessage({
currentDims: existing.dims,
requestedDims: resolvedDim,
requestedModel: resolvedModel,
source: 'init',
engineKind: 'pglite',
databasePath: dbPath,
}) + '\n');
if (opts.jsonOutput) process.exit(initJsonError({ status: 'error', reason: 'embedding_dim_mismatch', current_dims: existing.dims, requested_dims: resolvedDim },
'embedding_width_mismatch', `The brain's vectors are ${existing.dims}d; the requested model produces ${resolvedDim}d.`, INIT_EMBEDDING_HINT));
process.exit(1);
}
}
await engine.initSchema();
// v0.37.10.0 T6 (D11): post-initSchema invariant assertion. After preflight
// + always-configureGateway, this is structurally guaranteed to pass —
// kept as a regression guardrail so any future schema-substitution drift
// fails loud here, not at first embed.
if (resolvedDim) {
const { readContentChunksEmbeddingDim, embeddingMismatchMessage } = await import('../core/embedding-dim-check.ts');
const after = await readContentChunksEmbeddingDim(engine);
if (after.exists && after.dims !== null && after.dims !== resolvedDim) {
console.error('\nUNEXPECTED: post-initSchema invariant assertion failed.');
console.error(' This is a bug. Please file an issue with the output of `gbrain doctor`.\n');
console.error(embeddingMismatchMessage({
currentDims: after.dims,
requestedDims: resolvedDim,
requestedModel: resolvedModel,
source: 'init',
engineKind: 'pglite',
databasePath: dbPath,
}));
process.exit(1);
}
}
await writeNewInstallRerankerDefault(engine, resolvedModel);
const existingFile = loadConfigFileOnly() ?? ({} as GBrainConfig);
const config: GBrainConfig = {
...existingFile,
engine: 'pglite',
database_path: dbPath,
...(opts.apiKey ? { openai_api_key: opts.apiKey } : {}),
...(opts.aiOpts?.noEmbedding
? kept ? { embedding_model: kept.model, embedding_dimensions: kept.dimensions } : { embedding_disabled: true }
: (resolvedModel && resolvedDim)
? { embedding_model: resolvedModel, embedding_dimensions: resolvedDim }
: {}),
...(opts.aiOpts?.expansion_model ? { expansion_model: opts.aiOpts.expansion_model } : {}),
...(opts.aiOpts?.chat_model ? { chat_model: opts.aiOpts.chat_model } : {}),
// v0.42 (T17): default new brains to the schema_pack selected at init
// time. Existing config.schema_pack survives (...existingFile spread)
// unless explicitly overridden by --schema-pack on re-init.
...(opts.schemaPack ? { schema_pack: opts.schemaPack } : {}),
};
delete config.remote_mcp;
delete config.database_url;
// v0.46.3: leaving deferred-setup mode — a resolved (model, dims) tuple must
// also CLEAR a stale embedding_disabled sentinel inherited via the
// ...existingFile spread, or the documented recovery command
// (`init --force --embedding-model ...`) persists a config that still
// disables embedding at runtime.
if (!opts.aiOpts?.noEmbedding && resolvedModel && resolvedDim) {
delete config.embedding_disabled;
await recordInitEmbedding(engine, resolvedModel, resolvedDim);
}
// PR1: new installs publish their skill catalog over MCP by default
// (existing config wins on re-init, so a prior opt-out is preserved).
config.mcp = { ...(freshContentDatabase && !existingFile.engine ? { publish_skills: true } : {}), ...(config.mcp ?? {}) };
// v0.42: new installs default self-upgrade to NOTIFY (a nudge on every
// gbrain invocation). mode_prompted=true so the upgrade-time banner doesn't
// also fire on a fresh install. Hands-off: gbrain config set self_upgrade.mode auto
config.self_upgrade = { mode: 'notify', mode_prompted: true, ...(freshContentDatabase && !existingFile.engine ? { channel: 'stable' as const } : {}), ...(config.self_upgrade ?? {}) };
// MEMORY_VERBS v1 [D6C]: TTHW stamp — `gbrain protocol stats` derives
// install→first-verb-call from this. Idempotent on re-init.
config.protocol_installed_at = config.protocol_installed_at ?? new Date().toISOString();
preserveConversionConfig(false);
saveConfig(config);
if (freshContentDatabase) (await import('./migrations/fresh-install.ts')).recordFreshInstallMigrations();
if (freshContentDatabase) { const n = await import('../core/behavior-change-notice.ts'); n.stampFreshBrainBaseline(n.behaviorBrainKey(config)); }
const contentReceipt = await setupSharedBrainContent({ engine, config, sourceId: await resolveSourceId(engine, undefined), remote: false, dryRun: false, logger: { info: console.error, warn: console.error, error: console.error } }, {
...opts.content, fresh: freshContentDatabase,
...(process.env.GBRAIN_IN_AGENT_SETUP === '1' && !opts.content?.root ? { root: join(dirname(configPath()), '..', 'memory') } : {}),
});
if (!opts.jsonOutput) console.error(`[init] Content: ${contentReceipt.root ?? contentReceipt.repository_kind} (${contentReceipt.repository_kind}; ${contentReceipt.status}). ${contentReceipt.pending_actions.join(' ')}`);
if (opts.schemaPack) {
process.stderr.write(
`[init] Using schema pack: ${opts.schemaPack} (override with --schema-pack <name>)\n`,
);
}
// T6 (D7): post-init subagent-Anthropic caveat. Fires for both auto-pick
// and picker paths so users see the implication of running on a chat
// provider that can't drive the subagent loop.
if (opts.aiOpts?.chat_model && !opts.aiOpts.chat_model.startsWith('anthropic:') && !process.env.ANTHROPIC_API_KEY) {
const { printSubagentAnthropicCaveat } = await import('./init-provider-picker.ts');
printSubagentAnthropicCaveat((s) => process.stderr.write(s));
}
// v0.32.3 search-lite install-time mode picker. Runs AFTER initSchema so
// DB config writes are valid. Idempotent: skipped on re-init if already set.
// Non-TTY auto-selects; --json emits a structured event.
const { runModePicker } = await import('./init-mode-picker.ts');
let searchMode: { mode: SearchModeName; reason: string } | undefined;
await runModePicker(engine, { jsonOutput: opts.jsonOutput, ...searchModeChoice, onDecision: d => { searchMode = d; } });
const stats = await engine.getStats();
if (opts.jsonOutput) {
setInitJsonResult({ status: 'success', engine: 'pglite', path: dbPath, pages: stats.page_count, embedding_check: embedCheck, content: contentReceipt, ...firstRunJson(await firstRunBundle(engine, searchMode, registrationSurface)) });
} else if (process.env.GBRAIN_IN_AGENT_SETUP === '1') {
printInAgentReady(dbPath, freshContentDatabase);
} else {
console.log(`\nBrain ready at ${dbPath}`);
console.log(`${stats.page_count} pages. Engine: PGLite (local Postgres).`);
// Reference/status blocks print FIRST and terse; the ONE primary action
// (the memory demo) prints LAST so it is the final, unmistakable thing on
// screen. Krug: one obvious next action, everything else subordinate.
if (stats.page_count > 0) {
console.log('');
console.log('Existing brain detected. Wire up the knowledge graph:');
console.log(' gbrain extract links --source db (typed link backfill)');
console.log(' gbrain extract timeline --source db (structured timeline backfill)');
console.log(' gbrain stats (verify links > 0)');
}
reportModStatus();
// v0.41.18.0 (A4 + A18 + A20, T14): post-initSchema onboard nudge.
// Fail-open; 3s wallclock cap.
const { runInitNudge } = await import('../core/onboard/init-nudge.ts');
await runInitNudge(engine);
// G5: the ONE first-run decision bundle (search mode, writeback,
// harness wiring, skills scaffold); never blocks init.
writeCliNotices(await firstRunBundle(engine, searchMode, registrationSurface));
// The single primary action, last-on-screen.
printMemoryVerbsQuickstart({ emptyBrain: stats.page_count === 0, onPglite: true, keyless: config.embedding_disabled === true });
}
} finally {
try { await engine.disconnect(); } catch { /* best-effort */ }
}
}
const INIT_EMBEDDING_HINT = 'Pick an embedding model whose dimensions match (`gbrain init --help`), or pass --no-embedding for a keyless brain.';
/**
* MEMORY_VERBS v1 quickstart funnel (E3 + D4B + T1 consent). Printed LAST in
* both init epilogues as the ONE primary action. The copy-next block is
* three commands (codex DX 9): wire the harness (the readiness
* `harness_wiring` fix: absolute binary, `--surface full` or init's `--surface`), save an
* install-check marker (never a made-up fact about the user), and recall it.
* The demo uses the facts arm only, so it works with NO embedding key [F-B]. Secondary paths (import, migrate) ride a single terse
* "More:" footer so they never compete with the primary action.
*/
let registrationSurface: McpSurface | undefined;
let searchModeChoice: import('./init-mode-picker.ts').SearchModeChoice = {};
function printMemoryVerbsQuickstart(opts: { emptyBrain?: boolean; onPglite?: boolean; keyless?: boolean } = {}): void {
const register = harnessRegistrationCommand(registrationSurface);
console.log('');
console.log(`→ Do this next — give your agent memory (copy these ${register ? 'three' : 'two'} commands):`);
if (register) console.log(` ${register}`);
else console.log(' (register gbrain with your agent app first: install gbrain globally so the registration can use its absolute path, then follow docs/protocol/MEMORY_VERBS_v1.md)');
console.log(' gbrain remember "gbrain install check" --provenance install-check');
console.log(' gbrain recall --query "gbrain install check"');
console.log('Then ask your agent in a NEW session to recall "gbrain install check" — it remembers. Ask it to forget that fact afterwards.');
console.log('');
console.log('Note: memories agents save are readable by every agent connected to');
console.log('this brain; use visibility:"private" for local-only facts.');
console.log('Other harnesses (Codex, OpenClaw): docs/protocol/MEMORY_VERBS_v1.md');
console.log('If `claude` is not found: install Claude Code first, or use the per-harness blocks in that doc.');
// Secondary paths, one line, clearly subordinate to the action above.
console.log('');
console.log(
'More: ' +
(opts.emptyBrain ? `bulk-load notes \`gbrain import <dir>${opts.keyless ? ' --no-embed' : ''}\` · ` : '') +
(opts.onPglite ? 'scale up `gbrain migrate --to postgres --plan` · ' : '') +
'health `gbrain doctor`',
);
}
/**
* db-availability loop (5a): typed failure for initPostgresCore. The ladder
* (`init --prefer-postgres`) treats it as RUNG FAILURE and falls through to
* the next rung; the initPostgres wrapper preserves the historical
* process.exit(1) for direct `--supabase`/`--url` invocations.
*/
export class InitPostgresFailure extends Error {
constructor(public reason: string, message?: string) {
super(message ?? reason);
this.name = 'InitPostgresFailure';
}
}
/** Exit-preserving wrapper — direct invocations keep their contract. */
async function initPostgres(opts: Parameters<typeof initPostgresCore>[0]) {
try {
await initPostgresCore(opts);
} catch (e) {
if (e instanceof InitPostgresFailure) process.exit((opts.jsonOutput ? writeDeferredInitJsonError() : null) ?? 1);
throw e;
}
}
export async function initPostgresCore(opts: {
databaseUrl: string;
jsonOutput: boolean;
apiKey: string | null;
aiOpts?: ResolvedAIOptions;
/** v0.42 (T17): schema pack to default. */
schemaPack?: string;
/** v0.42 (#1780 Gap 2): skip the init-time embedding-key validation. */
skipEmbedCheck?: boolean;
content?: SharedContentOptions;
}) {
const { databaseUrl } = opts;
// v0.37.10.0 T6 (D11) + v0.37.11.0 Lane B.2: ALWAYS configure gateway BEFORE
// initSchema. Same preflight contract as PGLite. Refuse to call initSchema
// until the gateway-resolved dim is validated. PostgresEngine.initSchema()
// passes the resolved model and dimensions through getPostgresSchema(),
// which templates the static `vector(1536)` source before executing it.
// Preflight therefore prevents an invalid dimension from reaching schema
// generation, while the post-init assertion below guards against templating
// drift.
let resolvedDim: number | undefined;
let resolvedModel: string | undefined;
if (opts.aiOpts?.noEmbedding) {
if (!opts.aiOpts.implicitKeyless) console.log(deferredEmbeddingHint({ engine: 'postgres', database_url: databaseUrl, embedding_disabled: true }));
} else if (opts.aiOpts?.embedding_model) {
const { resolveSchemaEmbeddingDim } = await import('../core/embedding-dim-check.ts');
const pre = resolveSchemaEmbeddingDim({
embedding_model: opts.aiOpts.embedding_model,
embedding_dimensions: opts.aiOpts.embedding_dimensions,
});
if (!pre.ok) {
console.error(`\nRefusing to init: ${pre.error}\n`);
if (opts.jsonOutput) deferInitJsonError({ status: 'error', reason: 'preflight_failed', error: pre.error }, 'config_error', pre.error, INIT_EMBEDDING_HINT);
throw new InitPostgresFailure('preflight_failed', pre.error);
}
resolvedDim = pre.dim;
resolvedModel = pre.model;
}
// T6: unconditional configureGateway BEFORE initSchema.
const { configureGateway } = await import('../core/ai/gateway.ts');
// v0.46.3: keyless fresh installs size at the NEW-INSTALL width (see the
// PGLite path's comment — same explicit-param rationale).
const { NEW_INSTALL_DEFAULT_EMBEDDING_DIMENSIONS: newInstallDims } =
await import('../core/ai/defaults.ts');
if (resolvedModel) console.log(` Embedding: ${resolvedModel} (${resolvedDim}d)`);
if (opts.aiOpts?.expansion_model) console.log(` Expansion: ${opts.aiOpts.expansion_model}`);
if (opts.aiOpts?.chat_model) console.log(` Chat: ${opts.aiOpts.chat_model}`);
// Detect Supabase direct connection URLs and warn about IPv6
if (databaseUrl.match(/db\.[a-z]+\.supabase\.co/) || databaseUrl.includes('.supabase.co:5432')) {
console.warn('');
console.warn('WARNING: You provided a Supabase direct connection URL (db.*.supabase.co:5432).');
console.warn(' Direct connections are IPv6 only and fail in many environments.');
console.warn(' Use the Transaction pooler connection string instead (port 6543):');
console.warn(' Supabase Dashboard > Connect (top bar) > Connection String > Transaction pooler');
console.warn(' (With a pooler URL, gbrain derives a direct connection for DDL and falls back');
console.warn(' to the pooler automatically if that host is unreachable. Power users:');
console.warn(' GBRAIN_DIRECT_DATABASE_URL overrides the derived URL; GBRAIN_DISABLE_DIRECT_POOL=1 disables it.)');
console.warn('');
}
console.log('Connecting to database...');
const engine = await createEngine({ engine: 'postgres' });
try {
try {
await engine.connect({ database_url: databaseUrl });
} catch (e: unknown) {
const msg = e instanceof Error ? e.message : String(e);
if (databaseUrl.includes('supabase.co') && (msg.includes('ECONNREFUSED') || msg.includes('ETIMEDOUT'))) {
console.error('Connection failed. Supabase direct connections (db.*.supabase.co:5432) are IPv6 only.');
console.error('Use the Transaction pooler connection string instead (port 6543).');
console.error('(gbrain derives its own direct connection from pooler URLs for DDL; if that host is');
console.error('unreachable it falls back to the pooler. GBRAIN_DIRECT_DATABASE_URL overrides the');
console.error('derived URL; GBRAIN_DISABLE_DIRECT_POOL=1 disables the direct pool entirely.)');
}
throw e;
}
const freshContentDatabase = await isNewContentDatabase(engine);
await assertInitEmbeddingIdentity(engine, resolvedModel);
const kept = await keptEmbeddingIdentity(engine, opts.aiOpts, freshContentDatabase);
if (opts.aiOpts?.implicitKeyless) console.log(kept ? keptEmbeddingNotice(kept) : deferredEmbeddingHint({ engine: 'postgres', database_url: databaseUrl, embedding_disabled: true }));
configureGateway({
embedding_model: resolvedModel ?? kept?.model ?? opts.aiOpts?.embedding_model,
embedding_dimensions: resolvedDim ?? kept?.dimensions ?? opts.aiOpts?.embedding_dimensions ??
(opts.aiOpts?.noEmbedding ? newInstallDims : undefined),
expansion_model: opts.aiOpts?.expansion_model,
chat_model: opts.aiOpts?.chat_model,
env: { ...process.env },
});
const embedCheck = await runInitEmbedCheck({
resolvedModel,
resolvedDim,
expansionModel: opts.aiOpts?.expansion_model,
chatModel: opts.aiOpts?.chat_model,
apiKey: opts.apiKey ?? undefined,
noEmbedding: opts.aiOpts?.noEmbedding,
skipFlag: opts.skipEmbedCheck,
});
// Check and auto-create pgvector extension
try {
const conn = (engine as any).sql || (await import('../core/db.ts')).getConnection();
const ext = await conn`SELECT extname FROM pg_extension WHERE extname = 'vector'`;
if (ext.length === 0) {
console.log('pgvector extension not found. Attempting to create...');
try {
await conn`CREATE EXTENSION IF NOT EXISTS vector`;
console.log('pgvector extension created successfully.');
} catch {
console.error('Could not auto-create pgvector extension. Run manually in SQL Editor:');
console.error(' CREATE EXTENSION vector;');
// Throw so the outer finally runs engine.disconnect() before we die.
throw new Error('pgvector extension missing');
}
}
} catch (e) {
// 5b: the deliberate throw above used to be EATEN here, so an install
// with no pgvector "succeeded" into initSchema and died later with a
// worse message. Rethrow it; only the pg_extension PROBE failure stays
// non-fatal (odd hosted PG catalogs — initSchema surfaces the truth).
if (e instanceof Error && e.message === 'pgvector extension missing') throw e;
// Non-fatal: probe-read failure only.
}
// v0.28.5 (A4) + v0.37.11.0 Lane B.5: refuse to silently re-template an
// existing brain with a mismatched embedding dimension. Mirror of the
// PGLite path above. Fires even when the user didn't pass
// `--embedding-dimensions` explicitly so the Lane B.5 bare-init case is
// covered too.
if (resolvedDim) {
const { readContentChunksEmbeddingDim, embeddingMismatchMessage } = await import('../core/embedding-dim-check.ts');
const existing = await readContentChunksEmbeddingDim(engine);
if (existing.exists && existing.dims !== null && existing.dims !== resolvedDim) {
console.error('\n' + embeddingMismatchMessage({
currentDims: existing.dims,
requestedDims: resolvedDim,
requestedModel: resolvedModel,
source: 'init',
engineKind: 'postgres',
}) + '\n');
if (opts.jsonOutput) deferInitJsonError({ status: 'error', reason: 'embedding_dim_mismatch', current_dims: existing.dims, requested_dims: resolvedDim },
'embedding_width_mismatch', `The brain's vectors are ${existing.dims}d; the requested model produces ${resolvedDim}d.`, INIT_EMBEDDING_HINT);
throw new InitPostgresFailure('embedding_dim_mismatch');
}
}
console.log('Running schema migration...');
const { runInitSchemaWithRetry } = await import('../core/init-schema-retry.ts');
await runInitSchemaWithRetry(engine);
// v0.37.10.0 T6 (D11): post-initSchema invariant assertion guardrail.
if (resolvedDim) {
const { readContentChunksEmbeddingDim, embeddingMismatchMessage } = await import('../core/embedding-dim-check.ts');
const after = await readContentChunksEmbeddingDim(engine);
if (after.exists && after.dims !== null && after.dims !== resolvedDim) {
console.error('\nUNEXPECTED: post-initSchema invariant assertion failed.');
console.error(' This is a bug. Please file an issue with the output of `gbrain doctor`.\n');
console.error(embeddingMismatchMessage({
currentDims: after.dims,
requestedDims: resolvedDim,
requestedModel: resolvedModel,
source: 'init',
engineKind: 'postgres',
}));
throw new InitPostgresFailure('post_init_dim_invariant');
}
}
await writeNewInstallRerankerDefault(engine, resolvedModel);
// v0.37.10.0 T7 (D9) + v0.37.11.0 Lane B.4 (Postgres mirror): atomic
// embedding-config persistence on top of the existing file-plane config.
// Same precedence + same merge contract as the PGLite path above.
const existingFile = loadConfigFileOnly() ?? ({} as GBrainConfig);
const config: GBrainConfig = {
...existingFile,
engine: 'postgres',
database_url: databaseUrl,
database_path: undefined, // clear any stale PGLite path
...(opts.apiKey ? { openai_api_key: opts.apiKey } : {}),
...(opts.aiOpts?.noEmbedding
? kept ? { embedding_model: kept.model, embedding_dimensions: kept.dimensions } : { embedding_disabled: true }
: (resolvedModel && resolvedDim)
? { embedding_model: resolvedModel, embedding_dimensions: resolvedDim }
: {}),
...(opts.aiOpts?.expansion_model ? { expansion_model: opts.aiOpts.expansion_model } : {}),
...(opts.aiOpts?.chat_model ? { chat_model: opts.aiOpts.chat_model } : {}),
// v0.42 (T17): same schema_pack default as PGLite path.
...(opts.schemaPack ? { schema_pack: opts.schemaPack } : {}),
};
delete config.remote_mcp;
// v0.46.3: leaving deferred-setup mode — a resolved (model, dims) tuple must
// also CLEAR a stale embedding_disabled sentinel inherited via the
// ...existingFile spread, or the documented recovery command
// (`init --force --embedding-model ...`) persists a config that still
// disables embedding at runtime.
if (!opts.aiOpts?.noEmbedding && resolvedModel && resolvedDim) {
delete config.embedding_disabled;
await recordInitEmbedding(engine, resolvedModel, resolvedDim);
}
// PR1: new installs publish their skill catalog over MCP by default
// (existing config wins on re-init, so a prior opt-out is preserved).
config.mcp = { ...(freshContentDatabase && !existingFile.engine ? { publish_skills: true } : {}), ...(config.mcp ?? {}) };
// v0.42: new installs default self-upgrade to NOTIFY (a nudge on every
// gbrain invocation). mode_prompted=true so the upgrade-time banner doesn't
// also fire on a fresh install. Hands-off: gbrain config set self_upgrade.mode auto
config.self_upgrade = { mode: 'notify', mode_prompted: true, ...(freshContentDatabase && !existingFile.engine ? { channel: 'stable' as const } : {}), ...(config.self_upgrade ?? {}) };
// MEMORY_VERBS v1 [D6C]: TTHW stamp (see the PGLite path).
config.protocol_installed_at = config.protocol_installed_at ?? new Date().toISOString();
preserveConversionConfig(false);
saveConfig(config);
if (freshContentDatabase) (await import('./migrations/fresh-install.ts')).recordFreshInstallMigrations();
if (freshContentDatabase) { const n = await import('../core/behavior-change-notice.ts'); n.stampFreshBrainBaseline(n.behaviorBrainKey(config)); }
const contentReceipt = await setupSharedBrainContent({ engine, config, sourceId: await resolveSourceId(engine, undefined), remote: false, dryRun: false, logger: { info: console.error, warn: console.error, error: console.error } }, { ...opts.content, fresh: freshContentDatabase });
if (!opts.jsonOutput) console.error(`[init] Content: ${contentReceipt.root ?? contentReceipt.repository_kind} (${contentReceipt.repository_kind}; ${contentReceipt.status}). ${contentReceipt.pending_actions.join(' ')}`);
console.log('Config saved to ~/.gbrain/config.json');
if (opts.schemaPack) {
process.stderr.write(
`[init] Using schema pack: ${opts.schemaPack} (override with --schema-pack <name>)\n`,
);
}
// T6 (D7): post-init subagent-Anthropic caveat.
if (opts.aiOpts?.chat_model && !opts.aiOpts.chat_model.startsWith('anthropic:') && !process.env.ANTHROPIC_API_KEY) {
const { printSubagentAnthropicCaveat } = await import('./init-provider-picker.ts');
printSubagentAnthropicCaveat((s) => process.stderr.write(s));
}
// v0.32.3 search-lite install-time mode picker. Same shape as the
// PGLite path above — runs AFTER initSchema, idempotent on re-init.
const { runModePicker: runPostgresModePicker } = await import('./init-mode-picker.ts');
let searchMode: { mode: SearchModeName; reason: string } | undefined;
await runPostgresModePicker(engine, { jsonOutput: opts.jsonOutput, ...searchModeChoice, onDecision: d => { searchMode = d; } });
const stats = await engine.getStats();
if (opts.jsonOutput) {
setInitJsonResult({ status: 'success', engine: 'postgres', pages: stats.page_count, embedding_check: embedCheck, content: contentReceipt, ...firstRunJson(await firstRunBundle(engine, searchMode, registrationSurface)) });
} else {
console.log(`\nBrain ready. ${stats.page_count} pages. Engine: Postgres (Supabase).`);
if (stats.page_count > 0) {
console.log('');
console.log('Existing brain detected. Wire up the knowledge graph:');
console.log(' gbrain extract links --source db (typed link backfill)');
console.log(' gbrain extract timeline --source db (structured timeline backfill)');
console.log(' gbrain stats (verify links > 0)');
}
reportModStatus();
// v0.41.18.0 (A4 + A18 + A20, T14): post-initSchema onboard nudge.
// Fail-open; 3s wallclock cap.
const { runInitNudge } = await import('../core/onboard/init-nudge.ts');
await runInitNudge(engine);
// G5: the first-run decision bundle — same contract as the PGLite arm.
writeCliNotices(await firstRunBundle(engine, searchMode, registrationSurface));
// The single primary action, last-on-screen.
printMemoryVerbsQuickstart({ emptyBrain: stats.page_count === 0 });
}
} finally {
try { await engine.disconnect(); } catch { /* best-effort */ }
}
}
/**
* Quick count of .md files in a directory (stops early at 1000).
*/
function countMarkdownFiles(dir: string, maxScan = 1500): number {
let count = 0;
try {
const scan = (d: string) => {
if (count >= maxScan) return;
for (const entry of readdirSync(d)) {
if (count >= maxScan) return;
if (entry.startsWith('.') || entry === 'node_modules') continue;
const full = join(d, entry);
try {
let stat;
try {
stat = lstatSync(full);
} catch { continue; }
if (stat.isSymbolicLink()) continue;
if (stat.isDirectory()) scan(full);
else if (entry.endsWith('.md')) count++;
} catch { /* skip unreadable */ }
}
};
scan(dir);
} catch { /* skip unreadable root */ }
return count;
}
async function supabaseWizard(): Promise<string> {
// Non-TTY guard: without a terminal the URL prompt below can never be
// answered — the legacy behavior was a silent exit-0 no-op (stdin closed →
// readLine never resolved data → process ended with NO config written), the
// worst failure shape for a scripted/agent caller. Fail loud with the fix.
if (!process.stdin.isTTY) {
console.error('gbrain init --supabase needs an interactive terminal to prompt for the connection URL.');
console.error('Non-interactive: pass --url <connection_string>, or set GBRAIN_DATABASE_URL and use --non-interactive.');
process.exit(1);
}
try {
execSync('bunx supabase --version', { stdio: 'pipe' });
console.log('Supabase CLI detected.');
console.log('To auto-provision, run: bunx supabase login && bunx supabase projects create');
console.log('Then use: gbrain init --url <your-connection-string>');
} catch {
console.log('Supabase CLI not found.');
}
console.log('\nEnter your Supabase/Postgres connection URL:');
console.log(' Format: postgresql://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres?sslmode=require'); /* allow-pg-url-literal */
console.log(' Find it: Supabase Dashboard > Connect (top bar) > Connection String > Transaction pooler\n');
const url = (await promptLineStderr('Connection URL: ')) ?? '';
if (!url) {
console.error('No URL provided.');
process.exit(1);
}
return url;
}
/**
* v0.32.3 [CDX-9]: readLine + EOF detection + default fallback + timeout.
*
* The legacy readLine hangs forever if stdin closes (EOF mid-prompt) or
* the user never types anything. The mode-picker plan calls out "TTY
* closes mid-prompt → defaults to balanced" as a failure path, but the
* raw helper can't implement that contract.
*
* This wrapper:
* - Resolves to `defaultValue` if stdin emits 'end' before 'data'
* - Resolves to `defaultValue` if `timeoutMs` elapses with no input
* - Resolves to the typed value (trimmed) on normal data event
*
* `defaultValue` is returned VERBATIM when the user just hits Enter (empty
* data). That's the affordance that makes `Mode [balanced]: _` work.
*
* Non-TTY stdin (pipe, scripted init) returns defaultValue immediately
* without printing the prompt, so e2e tests don't hang.
*/
export async function readLineSafe(
prompt: string,
defaultValue: string,
timeoutMs: number = 60_000,
): Promise<string> {
// Non-TTY (pipe, redirect, scripted init) → no prompt, no wait.
if (!process.stdin.isTTY) return defaultValue;
// A5: the shared bounded reader (EOF / timeout → null → the default).
const answer = await promptLineStderr(prompt, { timeoutMs });
if (answer === null) process.stderr.write(`\n[no answer, using default: ${defaultValue}]\n`);
return answer ? answer : defaultValue;
}
/**
* Detect GStack installation across known host paths.
* Uses gstack-global-discover if available, falls back to path checking.
*/
export function detectGStack(): { found: boolean; path: string | null; host: string | null } {
// Try gstack's own discovery tool first (DRY: don't reimplement host detection)
try {
const result = execSync(
`${join(homedir(), '.claude', 'skills', 'gstack', 'bin', 'gstack-global-discover')} 2>/dev/null`,
{ encoding: 'utf-8', timeout: 5000 }
).trim();
if (result) {
return { found: true, path: result.split('\n')[0], host: 'auto-detected' };
}
} catch { /* binary not available */ }
// Fallback: check known host paths
const hostPaths = [
{ path: join(homedir(), '.claude', 'skills', 'gstack'), host: 'claude' },
{ path: join(homedir(), '.openclaw', 'skills', 'gstack'), host: 'openclaw' },
{ path: join(homedir(), '.codex', 'skills', 'gstack'), host: 'codex' },
{ path: join(homedir(), '.factory', 'skills', 'gstack'), host: 'factory' },
{ path: join(homedir(), '.kiro', 'skills', 'gstack'), host: 'kiro' },
];
for (const { path, host } of hostPaths) {
if (existsSync(join(path, 'SKILL.md')) || existsSync(join(path, 'setup'))) {
return { found: true, path, host };
}
}
return { found: false, path: null, host: null };
}
/**
* Install default identity templates (SOUL.md, USER.md, ACCESS_POLICY.md, HEARTBEAT.md)
* into the agent workspace. Uses minimal defaults, not the soul-audit interview.
*/
export function installDefaultTemplates(workspaceDir: string): string[] {
const gbrainRoot = dirname(dirname(__dirname)); // up from src/commands/ to repo root
const templatesDir = join(gbrainRoot, 'templates');
const installed: string[] = [];
const templates = [
{ src: 'SOUL.md.template', dest: 'SOUL.md' },
{ src: 'USER.md.template', dest: 'USER.md' },
{ src: 'ACCESS_POLICY.md.template', dest: 'ACCESS_POLICY.md' },
{ src: 'HEARTBEAT.md.template', dest: 'HEARTBEAT.md' },
];
for (const { src, dest } of templates) {
const srcPath = join(templatesDir, src);
const destPath = join(workspaceDir, dest);
if (existsSync(srcPath) && !existsSync(destPath)) {
mkdirSync(dirname(destPath), { recursive: true });
copyFileSync(srcPath, destPath);
installed.push(dest);
}
}
return installed;
}
/**
* Report post-init status including GStack detection and skill count.
*/
export function reportModStatus(): void {
const gstack = detectGStack();
const gbrainRoot = dirname(dirname(__dirname));
const skillsDir = join(gbrainRoot, 'skills');
let skillCount = 0;
try {
const manifest = JSON.parse(
readFileSync(join(skillsDir, 'manifest.json'), 'utf-8')
);
skillCount = manifest.skills?.length || 0;
} catch { /* manifest not found */ }
// One line per fact, one pointer per optional extra — this block sits on
// the init success screen, where every extra call-to-action competes with
// the memory-verbs funnel (the one action that matters). Krug: one screen,
// one primary action.
console.log('');
console.log('--- GBrain Mod Status ---');
console.log(`Skills: ${skillCount} loaded (router: skills/RESOLVER.md)`);
console.log(`GStack: ${gstack.found ? `found (${gstack.host})` : 'not found (coding skills — see github.com/garrytan/gstack)'}`);
// Retrieval Reflex (#1981): the deterministic pointer layer is ON by default
// (no action needed). The policy skill is installed into the HOST repo on
// request — we PRINT the pointer rather than silently mutating the host repo.
console.log('Retrieval reflex: on by default. More: `gbrain integrations` (policy skill), skills/soul-audit (identity).');
console.log('');
}
function printInitHelp() {
console.log(`
gbrain init — initialize a brain (PGLite or Supabase Postgres)
USAGE
gbrain init [flags]
ENGINE SELECTION (mutually exclusive)
--pglite Use embedded PGLite (zero-config, the default)
--supabase Use Supabase Postgres (recommended for 1000+ files)
--url <URL> Use a manual Postgres connection string
--mcp-only Thin-client mode: connect to a remote gbrain MCP, no local engine
OPTIONS
--force Overwrite an existing config (gated by default)
--non-interactive Don't prompt; use defaults
--migrate-only Apply pending schema migrations against the configured engine
without re-saving config (used by post-upgrade and orchestrators)
--json JSON output for status reporting
--content-root <path> Use a new owned content directory (existing source roots win)
--db-only Keep memory database-only; shared publication needs export/adoption
--git Authorize Git init in the new owned empty content directory
--no-git Keep a content directory without Git (default)
--path <DIR> Override default brain path (PGLite only)
--key <APIKEY> Provide an API key non-interactively (Supabase only)
--embedding-model <PROVIDER:MODEL>
e.g. openai:text-embedding-3-large, voyage:voyage-multimodal-3
--model <PROVIDER> Shorthand: pick recipe default for a provider
--embedding-dimensions <N>
Embedding dimensions (must match the model)
--expansion-model <PROVIDER:MODEL>
Model for query expansion (default: anthropic:claude-haiku)
--chat-model <PROVIDER:MODEL>
Default subagent driver (v0.27+)
--no-embedding Defer embedding setup (skips the embedding-key check)
--surface <verbs|starter|full> Tool surface the printed harness registration pins, listed in full
(default: starter, listing the memory verbs and request_tools)
--search-mode <conservative|balanced|tokenmax> Record the operator's search mode (no first-run ask; an existing brain's mode needs --force)
--skip-embed-check Skip the init-time embedding-key validation (config +
live test-embed). Also via GBRAIN_INIT_SKIP_EMBED_CHECK=1
EXAMPLES
gbrain init --pglite # Local-only, no API keys
gbrain init --supabase # Interactive Supabase setup
gbrain init --url postgresql://... # Use a custom Postgres
gbrain init --mcp-only --issuer-url https://host:3001 --mcp-url https://host:3001/mcp --oauth-client-id <id> --oauth-client-secret <secret> # Thin-client mode
NOTES
- Bare \`gbrain init\` always defaults to PGLite at ~/.gbrain/brain.pglite.
In a directory with 1000+ .md files it prints a suggestion to use
\`gbrain init --supabase\` (faster search at scale) but still proceeds
with PGLite.
- Existing config is preserved unless --force is passed.
`.trim());
}
/** Test-only seam (v0.48.2): the reranker-default write is pure enough to unit-test with a stub engine. */
export const _exports_for_test = { writeNewInstallRerankerDefault };