Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Embedding credential preflight.
*
* v0.41.6.0 D1 — fail fast at sync/embed/import entry when the configured
* embedding provider can't be reached. Without this, gbrain proceeds into
* the import phase, hits 565 per-file embed errors, writes 565 identical
* "OpenAI embedding requires OPENAI_API_KEY." rows to `~/.gbrain/sync-failures.jsonl`,
* and blocks the sync bookmark from advancing.
*
* Routes through `gateway.diagnoseEmbedding()` so the structured reason
* (missing_env / no_touchpoint / unknown_provider / etc.) drives a precise
* user-facing error message.
*
* Skip protocol: callers SHOULD NOT call validateEmbeddingCreds when the
* user explicitly passed `--no-embed` (the canonical opt-out). The
* deferred-setup sentinel is owned by `assertEmbeddingEnabled` in
* `embedding-dim-check.ts`; this preflight runs AFTER that check fires.
*/
import { diagnoseEmbedding, type EmbeddingDiagnosis } from './ai/gateway.ts';
/**
* Tagged error thrown by validateEmbeddingCreds. CLI catch sites format
* `.userMessage` to stderr and exit non-zero. The structured fields
* (`provider`, `model`, `missingEnvVars`, `reason`) enable programmatic
* consumers (`gbrain doctor --json`, future autopilot health checks) to
* read state without parsing the human message.
*/
export class EmbeddingCredentialError extends Error {
readonly diagnosis: EmbeddingDiagnosis;
readonly userMessage: string;
constructor(diagnosis: EmbeddingDiagnosis, userMessage: string) {
super(userMessage);
this.name = 'EmbeddingCredentialError';
this.diagnosis = diagnosis;
this.userMessage = userMessage;
}
}
/**
* Run the preflight. Throws EmbeddingCredentialError when the gateway
* can't serve embeddings. Returns silently when ok.
*
* Pure function: reads nothing except what `gateway.diagnoseEmbedding()`
* already had at gateway configure-time.
*/
export function validateEmbeddingCreds(): void {
const d = diagnoseEmbedding();
if (d.ok) return;
throw new EmbeddingCredentialError(d, formatEmbeddingCredsError(d));
}
/**
* Format a paste-ready, multi-line error message from a non-ok diagnosis.
* Exported for tests and for the doctor JSON output.
*/
export function formatEmbeddingCredsError(d: EmbeddingDiagnosis): string {
if (d.ok) return '';
switch (d.reason) {
case 'no_gateway_config':
return [
'Embedding gateway is not configured.',
'This is usually a startup-order bug. Re-run with --no-embed to import',
'without embedding, then file an issue at https://github.com/garrytan/gbrain/issues',
].join('\n');
case 'no_model_configured':
return [
'No embedding model is configured for this brain.',
'',
// NOT `gbrain config set embedding_model` — that key is file-plane
// schema-sizing config the command refuses; init --force is the
// sanctioned re-configuration path.
' Set one: gbrain init --force --embedding-model voyage:voyage-4',
' Or skip embedding now: re-run with --no-embed',
].join('\n');
case 'unknown_provider':
return [
`Embedding model "${d.model}" uses an unknown provider "${d.provider}".`,
'',
` ${d.message}`,
'',
' Pick a known provider: gbrain init --force --embedding-model voyage:voyage-4',
].join('\n');
case 'no_touchpoint':
return [
`Provider "${d.provider}" does not offer an embedding touchpoint.`,
'',
' Switch providers: gbrain init --force --embedding-model voyage:voyage-4',
' Or run with --no-embed to import-only and embed later.',
].join('\n');
case 'user_provided_dims_unset':
return [
`Provider "${d.provider}" ships no default embedding dimension; set one explicitly.`,
'',
` Re-init with the dimension: gbrain init --embedding-dimensions <N>`,
' (embedding_dimensions is a schema-sizing field — `config set` rejects it on purpose)',
' Or run with --no-embed to import-only and embed later.',
].join('\n');
case 'missing_env': {
const envs = d.missingEnvVars.join(', ');
const primaryEnv = d.missingEnvVars[0];
const lines = [
`Embedding model "${d.model}" requires ${envs}.`,
'',
`Set it in your shell, or:`,
` • Re-run with --no-embed to import-only and embed later once the key is set.`,
];
// Only offer a provider-switch hint when the current provider isn't openai
// (otherwise we'd be suggesting they switch to the thing they already have).
if (d.provider !== 'openai') {
lines.push(` • Switch providers: gbrain init --force --embedding-model openai:text-embedding-3-small`);
} else {
lines.push(` • Switch providers: gbrain init --force --embedding-model voyage:voyage-4`);
}
lines.push('');
lines.push(`Example shell setup:`);
lines.push(` export ${primaryEnv}=...`);
return lines.join('\n');
}
}
}