Garry's Opinionated OpenClaw/Hermes Agent Brain
Key files: Core Ai
Subsystem index. Read only the entries relevant to your change. Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG.
src/core/ai/build-gateway-config.ts—buildGatewayConfig(c: GBrainConfig): AIGatewayConfig, re-exported bysrc/cli.ts. Lets core modules (init-embed-check.ts) reuse it without importing the CLI entrypoint. Delegates the file-plane API-key fold + env merge tomergedProviderEnv(src/core/ai/provider-env.ts); keeps ownership of threading local-server*_BASE_URLenv vars into base_urls.process.envwins EXCEPT empty-string / undefined values are dropped before the merge, so an injected emptyANTHROPIC_API_KEY=''(Claude Code neuters subprocess LLM calls this way) can't clobber a valid config-plane key;'0'/'false'are preserved. Pinned bytest/ai/build-gateway-config.test.ts.src/core/ai/call-log.ts+ the observer half ofsrc/core/ai/invocation-guard.ts— invocation observers and attribution.observeAIInvocations(observer)registers a process-level observer thatinvokeAInotifies once per call (guarded or not) with{ call, outcome: ok | error | refused, usage, startedAt, ms, attribution }; the unguarded branch ofguarded-generation.tsroutes throughinvokeAIonly while an observer is installed and passes the caller's transport options unchanged, so observation never alters retries, token defaults or admission (pinned bytest/ai-invocation-observer.test.ts). Observer throws are swallowed and counted (aiInvocationObserverFailures); adding the same function twice is a no-op.withAIAttribution({ request_id, effect, job_id, job_name, phase }, fn)merges into an async-local attribution read by observers: the persistence effect dispatcher (effects.ts), the in-process facts queue (facts/queue.ts, captured per entry at enqueue), thefacts-absorbjob handler (internal write-request id frompersistence_request_id) andtimeContainedPhase(cycle:<phase>) set it.installAICallLogFromEnv(called byconfigureGateway, idempotent per path) appends one JSON line per call toGBRAIN_AI_CALL_LOG(kind with multimodal counted as embedding, operation, model, outcome, ms, input/output/cache tokens orunknown, attribution; never prompt or response text; one warning on write failure). Pinned bytest/ai-call-log.test.ts.src/core/ai/chat-usage.ts+src/core/ops/usage.ts— durable per-call chat usage accounting.gateway.chat()callsrecordChatUsageat its SUCCESS boundary (production provider path AND test-transport path) with the answering model + token usage, andgateway.expand()does too on each successful expansion call with phaseexpansion, which wins over an ambient phase (#7176); think's synthesis call runs underwithDefaultChatPhase('think'), so it recordsthinkunless a job or cycle phase already attributes it; the record lands in thechat_usage_logtable (migration v140) via an injected sink (setChatUsageSink— no engine import here, so the gateway imports this leaf statically without deepening a cycle). Phase attribution is best-effort via AsyncLocalStorage (withChatPhase): the minion worker AND the cycle's inline drain (inline-drain.ts) both wrap handler execution injob:<name>, a cycle phase that meters its own spend wraps itself inphase:<name>(dream synthesize does), and direct callers record phase NULL. The innermost wrap wins, which is the point — a child drained INSIDE a wrapped phase must carry its ownjob:tag or the phase tag absorbs every child's spend and the ledger double-counts (one ledger per surface:minion_jobsstays the child-spend authority, the phase row is the orchestrator's own calls). Pricing resolves throughCANONICAL_PRICING(estimateChatCostUsd, cache_read/cache_write at provider cache rates when the table carries them); unknown models recordcost_usd = NULL, never a fake 0. Accounting is strictly fail-open + fire-and-forget: a sink error must never break a chat call.withChatCallMetercounts successful calls on aChatCallMeter(phase containment's{ calls }); a meter that declarescost_usd(the nightly probe's) also prices each call with the budget tracker's resolver (priceForwith the meter'spricing_overrides; a table row uses the same cache-awareestimateChatCostUsdvalue the record carries), counts an unpriced call inunpriced_callsinstead of as 0, and is priced even when no sink is registered. Theget_usageop (admin scope, NOT read —chat_usage_loghas no source dimension, so a source-restricted/federated token must not see brain-wide spend telemetry) returns per-model/per-phase aggregates only, plus an explicitcoverageblock stating what the ledger does NOT capture (subagent raw-SDK path, embeddings, pre-sink/pre-v140 calls, failed calls);budget-tracker.tsremains the pessimistic in-flight spend gate — this table is the after-the-fact ledger.src/core/ai/date-grounding.ts— the time vocabulary every extraction prompt shares: observation time (when text was written or said), event/validity time (facts.valid_from), recording time (created_at).resolveObservationDate(filename /date/published/ created keys viacomputeEffectiveDate; neverevent_date, row timestamps or now),observationDateFrom(turn/message timestamps),observationDateRule(static system-prompt rule: rewrite relative dates as absolute dates or bounds resolved against the observation date, never leaving the phrase beside its date; unknown → keep as written),observationDateLine(user-message date orunknown),parseExtractedEventDate(YYYY-MM-DD, 1900..now+1y),resolveValidFrom(extracted > caller > observation > now),hasUnresolvedRelativeDate(judge-free eval check). Fact extraction, dream synthesis, extract_atoms and propose_takes add the rule by default (extraction.date_groundingunset or true;falseturns all off; held-out verdict and per-consumer checks indocs/eval/decisions/p2-e2-heldout/); the life chronicle judge adds it only when the setting is explicitlytrue(isConsumerDateGroundingOn(engine, consumer)). Page-body facts default to the page's observation date regardless. Pinned bytest/ai/date-grounding.test.ts,test/facts/extract-date-grounding.test.ts,test/facts/backstop-page-date.test.ts.src/core/ai/defaults.ts— leaf module for canonical embedding and reranker defaults, without a gateway import. Voyagevoyage:voyage-4at 1024 dimensions is the new-install embedding default;voyage:rerank-3-liteis the runtime/mode-bundle reranker default (it applies only to brains with nosearch.reranker.modelrow).renderCanonicalMigrationCommandssupplies an explicit-target cost preview and an OpenAI keep-width alternative where supported. These constants do not establish the identity of vectors in an existing database and must never authorize automatic provider conversion. Init preserves explicit choices, writes no reranker row when the Voyage key is available, disables reranking for keyed installs without that key, and preserves keyless setup.src/core/ai/dims.ts— per-providerproviderOptionsresolver for embed-time dimension passthrough; the single source of truth for "which provider needs which knob to producevector(N)". ExportsdimsProviderOptions(implementation, modelId, dims)(called byembed()ingateway.ts),VOYAGE_OUTPUT_DIMENSION_MODELS(private const — the 7 hosted Voyage models that acceptoutput_dimension:voyage-4-large,voyage-4,voyage-4-lite,voyage-3-large,voyage-3.5,voyage-3.5-lite,voyage-code-3— nano deliberately excluded),VOYAGE_VALID_OUTPUT_DIMS = [256, 512, 1024, 2048] as const,supportsVoyageOutputDimension(modelId),isValidVoyageOutputDim(dims). Voyage path uses the SDK-supporteddimensionsfield ({ openaiCompatible: { dimensions: N } }), NOT Voyage'soutput_dimensionwire-key — thevoyageCompatFetchshim ingateway.ts:541translatesdimensions → output_dimensionbefore the HTTP body is built (the AI SDK's openai-compatible adapter doesn't recognize the wire-key, so sending it from here would be silently dropped and Voyage would return its default 1024-dim). Runtime guard: when a Voyage flexible-dim model is configured withdimsoutsideVOYAGE_VALID_OUTPUT_DIMS, throwsAIConfigErrorwith a paste-readygbrain config set embedding_dimensions <256|512|1024|2048>hint at the embed boundary (most common trigger:embedding_model: voyage:voyage-4-largewithoutembedding_dimensions, retaining an incompatible 1536-dimensional setting from another provider). Every lookup in this module folds through the privatemodelMatchKey(trim + lowercase) so cased hub-form ids (Qwen/Qwen3-Embedding-4B) match the all-lowercase tables — the folded key is a MATCH key only, never sent to a provider (wire model ids are case-sensitive; error messages keep the original id so they stay paste-ready); the Qwen3-Embedding native-width table lives at module scope alongside the other dim tables. Consequence, deliberate: a cased Voyage/Perplexity config matches and fails loudly at init when itsdimsis invalid, rather than skipping validation and silently producing wrong-width vectors.src/core/ai/embed-batch-plan.ts— the embedding request plan shared byembed()and spend preflights: per-input truncation (EMBED_MAX_CHARS), themax_batch_tokens× safety-factor pre-split (splitByTokenBudget, re-exported by the gateway), the item cap (capBatchItems,NO_BATCH_CAP_SUB_BATCH_ITEMSforno_batch_caprecipes) and the per-request input ceiling a guard reserves (embedRequestMaxInputTokens: one token per UTF-8 byte, capped per text by a declaredmax_input_tokens, additive so any split or retry of the same texts stays inside it).embedRequestCeilings(texts, model)replays the plan for a model string without a gateway;rerankRequestMaxInputTokensis the rerank twin. Pinned bytest/embedding-migration-settle.serial.test.tsand the adaptive-batch suites.src/core/ai/embedding-guard.ts— the embedding refusal contract (#4616).degenerateEmbeddingReasonflags zero-norm (L2 norm belowEMBEDDING_NORM_EPSILON), NaN and ±Inf vectors;sendableEmbeddingInputskeeps empty and whitespace-only inputs away from the provider;screenEmbeddings/screenAlignedEmbeddingsput vectors back at their input positions and throwEmbeddingZeroNormError(anAIConfigError,code: embedding_zero_norm, docsdocs/guides/write-refusals.md#embedding_zero_norm) carrying per-itemfailuresand the usablevectorsaligned with the input (null where refused).mergeZeroNormErrorsre-aligns per-slice refusals.suggestionFor(slug, sourceId?)fills thegbrain embed <slug>recovery command.fitMatryoshkaPrefix(recipe, modelId, vector, expected)(PR #5921, wave 14): when the recipe's embedding touchpoint declares the model inmatryoshka({ native, prefixes }, folded ids;recipes/nvidia.tsdeclares Nemotron-3-Embed-8B at 4096 with 1024/2048) and the provider answered at the native width for a listed target, the vector is sliced from the start and L2-normalized beforegateway.embedSubBatch's dim-mismatch check; every other vector returns untouched, an overflowing norm is refused, a zero or non-finite prefix falls to the per-item screen. Consumers:gateway.embed()and both multimodal embedders,embedding.ts:embedBatch(later 100-input slices still run),embed-retry.ts(never retried;embedBatchKeepingUsablereturns the partial result),embed.ts:embedPageTextsand markdown/code imports (usable vectors stored, refused chunks stay NULL and the page signature is not stamped). Tests:test/embedding-zero-norm-4616.serial.test.ts(+ Postgres wrapper).src/core/ai/engine-gateway.ts+src/core/engine-scope.ts(GBRA-283 B2) — the AI gateway of an engineopenEngineopened.engineGatewayInput(settings)builds itsAIGatewayConfigfromsettings.ai(provider id →apiKey/baseUrl, folded into the recipe's key env name andbase_urlsor the native*_BASE_URL) andsettings.embedding, neverprocess.envor~/.gbrain/config.json;scopedGatewayStatekeeps one state (config, model clients, a query-cache tag, batch-shrink, no-key and structured-output memory) per held settings object, so a disconnect drops it;settings.cache_namespacetags that engine's cached query embeddings instead (B3a).engineProviderProblemrefuses claude-cli and recipes withresolveOpenAICompatConfig(Azure).gateway.tsreadsgw()(that state in an embedded engine's scope, else the process stateconfigureGatewaywrites) andconfigFor(recipe, touchpoint)refusesengine_scope_missingbefore any call to a provider the engine lacks; a call with no scope while the process holds an open embedded engine refusesengine_scope_required(refuseUnscoped) whateverconfigureGatewayset; discovery andconfigureGatewayIfUninitializedskip engine states, andanthropic-key.tsanswers the scoped engine's own key.withEngineScope(engine, fn)(AsyncLocalStorage,engine-scope-store.ts; entered even before the first embedded engine opens) is entered by every operation handler (operation-load.ts), each persistence consumer (persistence/service.ts), minion jobs,POST /mcp, andhybridSearchand the import paths (needsEngineScope: once an embedded engine has opened, any engine other than the scoped one);withLocalScope(fn)marks a call for the process gateway (the CLI,serveandjobsenter it);embeddedEngineInScoperesolves throughengineKey.engine-construct.tsbuilds an engine without the process chat-usage sink (createEngineadds it), soopenEngineregisters a sink of its own. Pinned bytest/engine-gateway.test.tsandtest/engine-scope-required.test.ts(refusals, two engines, transaction/proxy/degraded sharing, a byte-identical process gateway for other engines, a canary key absent from errors, logs, doctor and read-back).src/core/ai/errors.ts— error normalization and classification. One private generator,wrappedErrorLayers, opens a thrown error's wrappers outermost first (cause, else RetryError'slastError; objects only, at most five layers, a repeated layer ends the walk).isStructuredOutputRejectionandreadProviderFailureSignalsuse it; the latter returns the first finitestatus/statusCode/apiErrorStatusplus every stringnameandcodeand never throws (a throwing getter ends the walk).page-summary.tsclassifyChatErrorreads those signals, so a wrapped claude-cli 429, an AI SDK RetryError's 429/5xx or aTimeoutError/network code oncauseclassifies as rate_limit/provider_5xx/timeout/network instead ofmalformed(which drops the page to the title tier).classifyGlobalLlmErrorkeeps its own depth-3 loop overcause ?? lastError, so a 404 there halts asmodel_not_found; the model-not-found phrases (model_not_found,not_found_error, "does not exist or you do not have access", "does not have access to [the] model") are tested before the status map, so a provider 403 that denies a project access to a model classifiesmodel_not_foundwith the model fix, neverauth(a plain 401/403 staysauth;test/ai/model-not-found-class.test.ts). #5304:normalizeAIError(err, context, redact, routeHint)appendsrouteHintto a 404's fix only;src/core/ai/model-not-found-hint.tsrenders it from the gateway's recorded provenance (gatewayModelNotFoundHint(touchpoint, model)→modelRouteHint: "Selected via models.tier.reasoning. Fix: gbrain config set models.tier.reasoning :"; env and config.json pins say what to clear; a deprecated key names themodels.*key to set instead; the built-in default names the touchpoint's tier key; unrecorded or stale provenance adds nothing) andembeddingModelNotFoundHint()namesembedding_modelwith the doctor route, never a bareconfig set.gateway.tspasses it at itsembed,expandandchat404 sites (test/ai/model-not-found-hint-5304.test.ts); the--- raw ---phrase barrier and billing-over-429 precedence hold (test/synopsis-chat-failure-class.test.ts,test/ai/classify-global-llm-error.test.ts). #6816:providerContentBlockReasonalso returnsclaude_cli_usage_policyfor the claude-cli adapter's usage-policy refusal (ClaudeCliProcessError, noapiErrorStatus,claude-cli reported error: API Error:prefix, the AUP link and a refusal phrase:CLAUDE_CLI_REFUSAL_RE);test/claude-cli-refusal-6816.test.ts. #9466:normalizeAIErrorturns a success response whose body the AI SDK could not parse as one JSON document (AI_JSONParseError, alone or as the cause of a 2xxAI_APICallError) into a non-retryableAIConfigErrorwith codeprovider_response_unparseable(UNPARSEABLE_RESPONSE_CODE) and fixed text that quotes no response body;facts/extract.tsputs that code in its cause label andfacts/dead-absorb-retry.tsclassifies itnot_retryable(test/ai/unparseable-success-response-9466.test.ts).src/core/ai/gateway.ts— unified seam for every AI call. TheaiSDK loads at the first provider call (lazy default transports), not on configure.embedQuery(text, opts?)andisAvailable(touchpoint, modelOverride?)accept a model override so the resolved-column path embeds via the column's provider (Voyage / OpenAI) instead of the global default; the hybrid path passes{embeddingModel: resolved.provider, dimensions: resolved.dimensions}and the gateway resolves the matching recipe viainstantiateEmbedding().isAvailable('embedding', 'voyage:voyage-3-large')checks the override's recipe (not the default) so hybrid skips vector search only when the active column's provider is actually down.voyageCompatFetchadapts Voyage embedding requests and responses;openAICompatAsymmetricFetchthreads explicit query/document input types for other compatible recipes through the SDK boundary.gateway.rerank()native HTTP path (no AI-SDK reranking abstraction): resolves the EFFECTIVE reranker asinput.model ?? getRerankerModel() ?? DEFAULT_RERANKER_MODEL(imported fromai/defaults.ts;voyage:rerank-2.5), posts to the recipe's reranker path (touchpoints.reranker.path, default/rerank; supported recipes declare their path explicitly) with bearer auth — the request's top-N key is recipe-pluggable viatouchpoints.reranker.top_param(defaulttop_n; Voyagetop_k) — and returnsRerankResult[]sorted by relevance.no_keypreflight: afterrequireConfig(), a recipe without a customresolveAuthwhoseauth_env.requiredkey is absent fromcfg.envthrowsRerankError('no_key')BEFORE any HTTP —noKeyOnce()writes ONEno_keyaudit row per process per model without a stderr line, avoiding per-query noise.auththerefore means "key present but rejected" (HTTP 401/403).RerankError.reasonclassifier:auth | no_key | rate_limit | network | timeout | payload_too_large | unknown. 5s default timeout (search hot path). Pre-flight payload guard rejects bodies overrecipe.touchpoints.reranker.max_payload_byteswithreason: 'payload_too_large'._rerankTransporttest seam mirrors_embedTransport.embedQuery(text)threadsinputType: 'query'throughdimsProviderOptions()(4-arg).getRerankerModel()returns only the EXPLICITLY configured model (callers need not pre-check availability —rerank()failsno_keyitself; the sync readiness predicate for dashboards isreranker-readiness.ts) +isAvailable('reranker')branch;configureGateway+reconfigureGatewayWithEnginethreadreranker_model;applyResolveAuth+defaultResolveAuthwiden touchpoint param to include'reranker'.embedMultimodalOpenAICompat()routes recipes withimplementation: 'openai-compatible'(LiteLLM, Anyscale, vLLM, Gemini multimodal via proxy) through the standard/embeddingsendpoint with content arrays carryingimage_urlentries; the Voyage/multimodalembeddingspath is unchanged (gateway selects by recipeimplementationtag). Runtime dimension validation throwsAIConfigError(with model id + observed + expected) before the vector reaches storage when the provider returns a width that doesn't match the recipe'sdefault_dimsor the brain'sembedding_dimensions. Pinned bytest/openai-compat-multimodal.test.ts. Module-scoped_embedTransportdefaults to AI SDKembedMany, with__setEmbedTransportForTests(fn)test seam so tests driveembed()with a stubbed transport.splitByTokenBudgetandisTokenLimitErrorexported@internal(pure functions reused by the test file). Module-level_shrinkState: Map<recipeId, {factor, consecutiveSuccesses}>halves the recipe's effectivesafety_factoron token-limit miss (floor 0.05) and heals back ×1.5 afterSHRINK_HEAL_AFTER=10consecutive successes.configureGateway()walks every registered recipe at construction and emits a once-per-process stderr warning for any embedding touchpoint missingmax_batch_tokens(excluding the canonical OpenAI fast-path).resetGateway()clears_shrinkState, the warned-set, and restores the real transport.embedMultimodal()readscfg.embedding_multimodal_modelfirst (falls back tocfg.embedding_model); after the recipe-levelsupports_multimodalfast-fail, validates the resolved model againsttouchpoint.multimodal_modelswhen declared (closes the Voyage-text-only-into-multimodal-endpoint footgun before any HTTP call).getMultimodalModel()accessor mirrorsgetEmbeddingModel/getChatModel.src/core/ai/multimodal-model.ts:multimodalEmbeddingModel()answers the modelembedMultimodal()would use when it passes those same recipe and allow-list checks (null otherwise, or when the gateway is unconfigured); hybrid search routes an inferred image intent and the LLM modality tie-break to the image arm only when it is set (test/cross-modal-hybrid-integration.serial.test.ts). ExportedVoyageResponseTooLargeErrortagged class:voyageCompatFetch's two OOM-defense caps (Layer 1 Content-Length, Layer 2 per-embedding base64) throw it; the inbound response-rewriter's try/catch (which swallows parse failures so misshaped responses fall through to the SDK parser) checksinstanceof VoyageResponseTooLargeErrorand rethrows so the cap is actually effective (test/ai/gateway.test.tsdrives both layers throughembed()). AI SDK v6 toolLoop compat (gbrain skilloptrollouts AND production backgroundsubagentjobs both route throughchat()/toolLoop): inchat(), tool defs wrap the raw JSON Schema with the SDK'sjsonSchema()helper (inputSchema: jsonSchema(t.inputSchema)) — v6'sasSchema()treats a bare{jsonSchema: ...}object as a thunk and throws "schema is not a function"; exported puretoModelMessages(messages: ChatMessage[]): unknown[]converts gbrain's provider-neutralChatMessage[]into v6ModelMessage[]— tool results (pushed bytoolLoopasrole:'user'with bare-value tool-result blocks) become a dedicatedrole:'tool'message with structuredoutput:{type:'json'|'text'|'error-text', value}parts;nulloutput preserved as{type:'json', value:null}(not dropped); text/tool-call blocks pass through with v6 field names (toolCallId/toolName/input); applied at thegenerateTextcall (messages: toModelMessages(opts.messages)). The converter is load-bearing for the production subagent path, not just skillopt. Pinned bytest/gateway-model-messages.test.ts. Companion:src/core/skillopt/rollout.tsbuilds tool schemas through the sharedparamDefToSchemafromsrc/mcp/tool-defs.ts(single source of truth, recursive on items/enum/default), never an inline converter. Provider-agnostic plumbing:resolveNativeBaseUrl(provider, cfg)normalizes a configuredANTHROPIC_BASE_URL/OPENAI_BASE_URLto carry the/v1suffix and is passed explicitly at every nativecreateAnthropic/createOpenAIsite (chat/expansion/embedding), so an env-injected bare host doesn't 404; returnsundefinedwhen unset so the SDK default is preserved (Google too:docs/ai-providers/google.md).diagnoseEmbeddingfails closed withuser_provided_dims_unsetwhen a user-provided / zero-default recipe (litellm/llama-server) has no configuredembedding_dimensions.configureGatewaydoes not backfillembedding_dimensions(readers default it themselves), keeping the "no dims set" signal honest for that guard and the multimodal skip.withBudgetTracker: gateway-layer enforcement viaAsyncLocalStorage<BudgetTracker>.withBudgetTracker(tracker, fn)installs the tracker on the module-internal store; everygateway.chat / embed / rerankcall inside the scope auto-composes (reserve before, record in try/finally). Outside-scope calls are budget no-ops. Nested scopes restore the outer tracker on exit.getCurrentBudgetTracker()is the test seam. The chat path uses the pessimistic fallback on error paths; the embed path estimates input tokens from char count × recipe'schars_per_tokenbecause the AI SDK doesn't surface per-batch embed token usage; the rerank path estimates char count of query+docs. Pinned by 6 unit cases.reconfigureGatewayWithEngine(engine)(async, called fromcli.tsafterengine.connect(), before every command exceptCLI_ONLYno-DB commands) re-resolves expansion + chat defaults throughresolveModel()somodels.tier.*andmodels.defaultoverrides apply to both.DEFAULT_CHAT_MODELisanthropic:claude-sonnet-4-6.ChatOpts.timeoutMsreplaces the default chat backstop (GBRAIN_AI_CHAT_TIMEOUT_MS, 300 s) for one call andToolLoopOpts.turnTimeoutMsforwards it to every turn (the subagent handler's per-turn cap, #4921);ChatOpts.thinking: 'off'maps per route throughthinking-off.ts(#5331).ChatOpts.temperatureis threaded verbatim to the AI SDKgenerateTextcall (unset → the provider's default; the LongMemEval judge pins0, the officialevaluate_qa.pysetting).ChatResult.responseModelcarries the model id the PROVIDER reported (response.modelId, e.g. a dated snapshot) when the SDK surfaced one and is absent otherwise, whilemodelstays the requestedprovider:modelId; eval receipts pin the two side by side (reader_model_snapshot,judge_model_snapshot).__setChatTransportForTestsmirrors__setEmbedTransportForTestsso tests drivechat()with a stubbed transport.toolLoopper-turn permit hook: optionalacquireTurnPermit()acquires a provider permit before EVERY round-trip and releases in finally; a lease-full throw propagates without consuming the turn (the subagent path wires it to the rate leases with provider-derived keys — Anthropic models shareanthropic:messages, others get<recipeId>:chat).ToolLoopStopReasonincludes'length': a zero-tool-call turn that hit the output cap propagates 'length' instead of folding into 'end', so truncation is never reported as a clean finish; and'empty_response'(#6448): a zero-tool-call clean stop whose text is empty or whitespace-only, so a refusal body or thinking-only turn is never reported as a finished answer (the subagent handler maps it toerror). Per-part provider state:ChatBlockvariants carry optionalproviderMetadatacaptured from SDK parts inchat()and re-emitted asproviderOptionson the rebuilt parts intoModelMessages()(attached only when present — metadata-free blocks stay byte-identical); this is the Gemini 3.x thoughtSignature echo.isThinkingByDefaultModel(modelStr)(exported) matches Claude 5-family ids behind any provider-prefix chain with a letters-only family segment (neverclaude-3-5-*);isThinkingModel(modelStr)(exported) is that regex OR the recipe's chatthinking_by_defaultcapability (fail-closed: unknown/chat-less recipes are non-thinking) and drivesdefaultMaxOutputTokens's 32k thinking headroom for chat()/toolLoop() callers that omit maxTokens (e.g.gbrain skilloptrollouts) and the subagent handler'sresolveMaxOutputTokens; think/index.ts shares the regex and makes the same capability check. Pinned bytest/ai/gateway-thinking-headroom.test.ts.expand()andgenerateOcrText()also record on the ambient tracker (they call generateObject/generateText directly and never pass throughchat()'s_recordBudget): record-only, no reserve — a breach surfaces on the NEXT reserving call, matchingchat()'s swallow ofBudgetExhaustedfromrecord(). Successes record normalized SDK usage vianormalizeSdkUsage(the ONE home for the v6/legacy usage shapes, used by chat's success path too; first FINITE field wins so a NaN v6 field can't shadow a real legacy value or poison the running total); failures record pessimistically undergateway.expand.failed/gateway.ocr.failed(a rejected attempt still billed provider tokens — one expand() can legitimately produce two records when the structured-output attempt fails and the text fallback runs). A recipe whose declared structured-output support is rejected at call time is remembered for the process lifetime (_structuredOutputRejectedRecipes) so the rejected attempt isn't re-paid on every call. OCR's input estimate is prompt text + a fixed per-image token constant, never base64 length (bytes are not tokens).generateOcrText()routes togetImageOcrModel()—embedding_image_ocr_modelwhen set, else the expansion model — gated byisAvailable('expansion', <ocr model>)so a misconfigured OCR model (provider without an expansion touchpoint, or unkeyed) fails closed to''instead of silently OCRing with the expansion model; the accessor mirrorsgetMultimodalModel(),configureGateway/buildGatewayConfigthread the field, and an unconfigured gateway stays a silent''no-op. Pinned bytest/ai/ocr-model-routing.test.ts.__setGenerateObjectTransportForTestsmirrors the generateText seam.ChatOpts.responseSchema({ name, description?, schema }) is honored ONLY when the resolved recipe is openai-compatible AND declaressupports_structured_outputs:chat()attaches a tolerantOutputspec (jsonSchemaOutput— carries the{ type: 'json', schema, name }responseFormat the provider turns intoresponse_format: json_schema, andparseCompleteOutputhands the raw text back instead of throwingNoObjectGeneratedErrorthe wayOutput.objectdoes on unparseable text) to the generateText call, soresult.text, stopReason mapping, budget recording and the caller's own parse + retry lane run unchanged; native / claude-cli lanes and undeclared openai-compatible recipes never see the field. A declared recipe whose backend REJECTS the schema at call time (isStructuredOutputRejectioninerrors.ts: a request-shaped 4xx namingresponse_format/json_schema/ structured output — never a 5xx or an unrelated 400) gets ONE schemaless retry plus one warn line, and lands in_structuredOutputRejectedRecipesso laterchat()andexpand()calls skip the schema for the process lifetime instead of re-paying the rejection on every retry lane. +test/core/budget/expand-records-budget.test.ts+test/ai/gateway-ocr-budget.test.ts+test/facts-extract-structured-output.test.tsTracker recording goes throughsrc/core/ai/budget-record.ts:recordOnTracker(fail-open: a cap breach onrecord()surfaces on the nextreserve()); every chat/toolLoop/expand/embed/rerank/OCR record site passes the requested model,purpose(optional onChatOpts+ toolLoop opts; skillopt setsskillopt.optimizer|target|judge, engine-internal calls leave it null),failedon failure paths,countsAsCall: falsefor expand's structured-output fallback attempt andestimatedwhen tokens are char-estimated.reconfigureGatewayWithEnginerecords the expansion/chatResolveSource(file_configfor the servable config.json pin) insrc/core/ai/gateway-model-sources.ts; its getters answer only while the gateway still routes to the recorded model, so a later reconfigure reads as unknown instead of stale provenance.embedQuerycaches query vectors per process (src/core/ai/query-embed-cache.ts: 512-entry LRU, 10-min TTL), keyed by recipe, model id,base_urlsoverride, effective dims and the exact provider input (prefix + text). It stores only resolved vectors, as copies; the cache clears with_modelCache(configure, env refresh, engine re-stamp, reset,__setEmbedTransportForTests) and a generation counter drops an embed straddling a clear; an embed whose own engine closed mid-flight stores nothing. Document-sideembed()is never cached; a caller under an AI invocation guard skips the cache read. Prompt-cache breakpoints:cacheSystem: trueon a prompt-cache-capable route derives ONEcacheControlValue(config TTL override honoured) that marks the system block, the last tool def, the call-level auto marker and, since PR #6341, any user textChatBlockflaggedcache: true(toModelMessages(messages, cacheControlValue)mergesproviderOptions.anthropic.cacheControlonto that block); without a value the flag is dropped and the block is plain text, so non-caching routes and the claude-cli adapter (which joins text parts with\n) see the same prompt text. Pinned bytest/page-summary-prompt-cache.test.ts.src/core/ai/chat-fallback.ts: thechat_fallback_chainconsumer.gateway.chat()hands a call tochatWithFallbackwhen a chain is configured and the caller did not passallowFallback: false;configureGatewaynormalizes the chain withnormalizeChatFallbackChain(a comma-separated string, the env and DB form, is split). Attempts run the call's own model, then each chain entry not already tried (chatFallbackAttempts), each as a complete single-modelchat(), so budget, usage ledger, guardrails andChatResult.modelfollow the model that ran; an answer from a chain entry also carriesChatResult.fallbackFrom(the call's own model). A provider error (a claude-cli subscription limit arrives asapiErrorStatus429) or a structural refusal (stopReasonrefusal/content_filter) moves to the next model with one[ai.gateway]stderr line, and the first hop of a process queues onechat_fallback_hopsafety notice infallback-hop-queue.ts; withchat_fallback_on_refusal: false(ChatFallbackOptions.onRefusal, passed bychat()from the gateway config) a structural refusal is returned and a provider content block (providerContentBlockReason: a Gemini prompt block, or an HTTP 400 content-policy body such as OpenAIinvalid_prompt, Azurecontent_filteror DeepSeek "Content Exists Risk") is thrown instead of being sent on, while provider errors still fall back; a policy refusal (isAIInvocationPolicyErroror a BudgetTrackerBudgetExhausted, including an unpriced chain entry under an explicit cap) or the caller's own abort stops the chain, and a cancel that lands while an attempt refuses returns that refusal instead of forwarding it; an earlier refusal is returned in preference to a later error, otherwise the call's own model's error is thrown (the last failure logged), so retry and halt classification follow the configured model.toolLoopforwardsallowFallbackto every turn. Judge, critic and eval call sites pin their model: brainstorm judges, grade_takes, drift, the edge_contradictions judge (apply mode defaults from a per-model certification), voice-gate, eval-contradictions, notability-eval, takes-quality-eval, cross-modal eval, skillopt (judge, optimizer, rollouts), the LongMemEval reader and judge, the functional-area-resolver harness, themodels doctor/providers testprobes,decide()(its egress gate cleared one provider),auto_think(its BudgetMeter priced one model), andthinkwith an explicit--model; the synthesize triage and concept synthesis fall back. Pinned bytest/ai/gateway-chat-fallback.test.tsandtest/ai/chat-fallback-on-refusal.test.ts(refusal switch through the real loader on every plane, the once-per-process hop notice).src/core/ai/fallback-hop-queue.ts: the process-level queue for the first hop'schat_fallback_hopnotice (at most one per process; type-only imports so every drain site loads it cheaply). Drained by stdio MCP dispatch, the CLI op notice channel (src/cli/op-notices.ts) andfinishCliTeardown; never by HTTP, because the notice names models.src/core/ai/chat-fallback-planes.ts: where the effectivechat_fallback_chaincomes from, read without network, subprocess or inference.readChatFallbackPlanes(db)reads envGBRAIN_CHAT_FALLBACK_CHAIN> the config.json key > the DB row (parseDbChatFallbackChaininconfig-db-merge.ts) with the loader's rule that the first plane that speaks wins even when its value yields no chain, and returns the winner, shadowed values, unreadable planes and thechat_fallback_on_refusalvalue with its plane.diagnoseChatFallbackEntrychecks one entry by presence:provider:modelparse, known provider with chat, the provider's own credential (recipe env keys orauthPresent; forclaude-clithe binary on PATH orGBRAIN_CLAUDE_CLI_BIN), and a price when a key inUSER_CHAT_CAP_KEYSsets a user cap.chatFallbackRemovalFixis the per-plane removal guidance (DBgbrain config unset chat_fallback_chainwithdestructiveconsent →ask_user; env/file are the user's, with the restart note). Consumers: thechat_fallback_chaindoctor check and thebehavior_changesnotice.src/core/ai/sdk-warnings.ts— AI SDK provider warnings to stderr (#5892). The gateway callsinstallAiSdkWarningWriter()when it loads, which setsglobalThis.AI_SDK_LOG_WARNINGSto a writer with theailogger signature ({ warnings, provider, model }) that prints each warning in the SDK's own wording to stderr and never the SDK'sconsole.infobanner, which landed on stdout and broke--jsonoutput (the claude-cli model's v2-compat notice fires on every process's first call). A user-set value (falseor a function) is kept. Tests:ai-sdk-warnings.test.ts,json-stdout-ai-warnings.test.ts.src/core/ai/thinking-off.ts: the per-route mapping behindChatOpts.thinking: 'off'(#5331).thinkingOffControl(modelStr)is the per-model capability table: the provider-options namespace and keys to set, and whether they turn reasoning off (disables) or only set its floor. Full off: nativeanthropic,deepseek,openrouterwith adeepseek/model (thinking: { type: 'disabled' }), Gemini 2.5 Flash/Flash-Lite (thinkingConfig.thinkingBudget: 0), OpenAI gpt-5.1/5.2/5.4/5.5/5.6 and nativeparticle(reasoningEffort: 'none', sent asreasoning_efforton Chat Completions; pinned bytest/ai/recipe-particle.test.ts). Floor: Gemini 2.5 Pro (thinkingBudget: 128), Gemini 3.x (thinkingLevelminimal, orlowon 3.7/3.8 Flash and 3.x Pro, whereminimalis a 400), gpt-5/-mini/-nano (minimal), o-series (low). Other Gemini 3+ and OpenAI gpt-5/o-series reasoning ids get no option and the headroom. gpt-6 ids have no row (the pinned @ai-sdk/openai drops their effort, and no live check measured them), so they keep the requested cap that fence repair's measured defaultopenai:gpt-6.1-solis costed against. Only native recipes get an option; the two Google fields are never sent together.applyThinkingOffsets the keys, replacing a configured value under the same key while siblings such ascacheControlorpromptCacheKeysurvive;chat()applies it after the call-scopedproviderOptionsmerge, on the resolved recipe.thinkingOffMaxOutputTokenskeeps the requested cap where reasoning turns off and raises a route that keeps reasoning (a floor row, or no row andisThinkingModel) to the thinking headroom. gateway.tsthinkingOffOutputCap(model, requested)wraps it forchat()and for the takes-quality and cross-modal preflight estimates, so they price the cap the call sends. Callers: those two judges and the synthesize triage judge. Rows were checked live on 2026-10-07 (docs/fix-wave-notes/capy-wave-9-followups.md). Pinned bytest/ai/chat-thinking-off.test.ts(request bodies per route against a local stub, estimate parity per default panel model) andtest/ai/gateway-chat.test.ts.src/core/ai/model-resolver.ts— Recipe-touchpoint validator.assertTouchpoint(recipe, touchpoint, modelId)checks the PROVIDER's capability only (anthropic has no embedding touchpoint; voyage/ollama have no chat) and never gates on the model id. Recipemodels:arrays are informational — default-model selection (models[0]for--model <provider>shorthand and env-ready pickers), guard-test fixtures for the repo's own hardcoded defaults, andgbrain providers listdisplay — NOT a runtime allowlist, so frontier models newer than a recipe work without a recipe PR. A nonexistent id surfaces as the provider's ownmodel_not_foundat call time;gbrain models doctorlive-probes the configured models for a pre-flight check. Exception:gateway.rerank()keeps its own model-list check because each listed reranker id maps to a known request/response wire shape.embeddingDimsForModelmatches recipemodel_dimskeys exactly first, then case-insensitively with BOTH sides folded (configured ids arrive cased, and user-editable recipe tables can carry cased keys; without the fold a cased id would fall through todefault_dimsandgbrain initwould build a wrong-width column), before falling back todefault_dims.src/core/ai/openai-latest.ts— latest-model discovery: OpenAI defaults are NEVER pinned.refreshLatestOpenAIModels()(called lazily from the gateway'sdiscoverBeforeOpenAICall, once perreconfigureGatewayWithEngine, just before an OpenAI-routed chat, expansion or embedding call, never on engine connect (#6607: a brain that never calls OpenAI sends nothing even withOPENAI_API_KEYset; when the refresh changes the discovered tiers the gateway re-resolves its models before the call reads them), TTL 24h, 3s-bounded, fail-open,GBRAIN_MODEL_DISCOVERY=off|0kill switch — the test preload sets it; skipped, even forced, when agbrain setupreceipt for this install recorded provider use as declined —providerDeclineRecordinsrc/core/setup/local-receipts.ts, an unreadable record fails closed) fetches the account's ownGET /v1/models, ranks ids through a conservative grammar (parseOpenAIChatId: bare family aliasesgpt-N.M+ known tier suffixes sol/pro/terra/luna/nano/mini; dated snapshots,-chatInstant-class, realtime/image and UNKNOWN future suffixes are ignored — rot degrades to newest-known-shape, never a wrong pick), and maps the newest family onto the tier ladder (utility→cheap, reasoning/subagent→mid, deep→top). ONLY ids with a canonical pricing row are eligible (rankOpenAIChatModels's priced filter): BudgetTracker fails closed (no_pricing) under a cost cap, so an unpriced discovered default would brick budget-capped backfills — a newer-unpriced family warns once naming the missingmodel-pricing.tsrow. Result lands in<configDir()>/model-cache.json(atomic tmp+rename);latestOpenAITiers()is the SYNC read (stale cache beats static fallback — TTL gates refresh, never use) consumed byresolveTierDefault's openai entry and the dynamicgptalias. Pinned bytest/openai-latest.serial.test.ts.src/core/ai/openrouter-families.ts— single source of truth for which OpenRouter model families may drive the subagent (tool) loop:OPENROUTER_SUBAGENT_FAMILIES(currentlyanthropic/+deepseek/, each backed by a live abort/retry replay pin undertest/e2e/) +openrouterModelSupportsSubagentLoop(modelId)(takes the bare OpenRouter id, noopenrouter:prefix). Shared by the openrouter recipe's predicate and the subagent handler's auto-route so the two can never disagree; a new family gets its own live pin before joining the list.src/core/ai/provider-env.ts—mergedProviderEnv(cfg, env): THE canonical provider-key/env fold. Maps file-plane config keys (openai/anthropic/openrouter/voyage/dashscope/deepseek/litellm/together/google/azure_openai + azure endpoint/deployment/entra) to the env names recipes read, merges env on top (env wins ONLY for keys carrying a real value — '' and undefined dropped), then applies theGEMINI_API_KEY → GOOGLE_GENERATIVE_AI_API_KEYalias (canonical env name > alias > config fallback). Three consumers:buildGatewayConfig(gateway env),detectCapabilities(capability probe),resolveTierDefault/resolveEffectiveChatModel(key-aware model resolution) — so gateway env and the capability probe cannot drift. #5137: the fold reads theCONFIG_API_KEY_ENVtable;providerKeyShadows(fileCfg, env)(pure, names only) lists env values that override a different config-plane key, andproviderKeySourcenames where a recipe's key comes from. Both take the FILE-only config (loadConfigFileOnly), becauseloadConfigalready folds OPENAI/ANTHROPIC/OPENROUTER env values into the config fields. TypeSafe has no config key, so its env alias never shadows. Tests:embedding-key-source.test.ts,embedding-key-source-cli.test.ts.src/core/ai/chat-key-probe.ts—probeChatModelWithKey(model):probeChatModelplus an up-front key check for every keyed provider (recipeauth_env.requiredagainstmergedProviderEnvover process env, the gateway env snapshot and the config file; Anthropic keepsprobeChatModel's check; keyless recipes pass). The hint namesgbrain config set <key>only whenCONFIG_API_KEY_ENVhas one. Used by the propose_takes and patterns cheap keyless skips (#6705);probeChatModelkeeps its lazy A9 contract. Pinned bytest/ai/gateway-probe-chat-model.test.ts.src/core/ai/key-warnings.ts— #5137 print seam with one replaceable sink and two once-per-process latches:warnShadowedProviderKeys(called fromsrc/cli.tsfor every command exceptgbrain hook;gbrain servestarts through the same path) names the variable, the config key, that env is in effect, and both fixes (remove the variable from that process's environment and restart it, orgbrain config unset <key>, which also silences it);reportEmbeddingAuthFailureprintsembedding_auth_failed(catalogue entry) on the first embedding 401/403, naming the key source in effect and the fix plusgbrain embed --stale. Never prints a key or fragment. Doctorembedding_key_source(src/commands/doctor/checks/embedding-health.ts, engine-free filesystem-lane entryembeddingKeySourceEntry) reports the same shadows and the embedding key's source, and says it sees only the environment doctor runs in.src/core/ai/key-redact.ts—redactProviderKeys(text, env): scrubs every*_API_KEY/*_TOKEN/*_SECRET/*_PASSWORDvalue in the gateway env, masked echoes (sk-...****abcd) and 8+ character key fragments from upstream error text. The gateway passes it tonormalizeAIError(which also scrubs the wrapped error's cause chain in place, keeping status and headers for.causewalkers) on embed, multimodal, expand and chat errors, and applies it to multimodal response bodies.src/core/ai/reranker-readiness.ts— pure leaf answering "is the reranker actually going to run?" forgbrain search modes(buildModesReport.reranker_readiness), doctor'sreranker_health, and init's reranker-default write.rerankerReadiness(model, env, { baseUrlOverrides? })→{model, provider, modelId (alias-canonical), recipeKnown, hasTouchpoint, modelListed, requiredKey (the first MISSING key, else the first required key — this is howReranker: … VOYAGE_API_KEY presentrenders; null only for keyless recipes), keyPresent, selfHosted, ready}; the env snapshot comes from the CALLER — the leaf never readsprocess.envand never imports the gateway (init runs beforeconfigureGatewayand passesmergedProviderEnv(cfg, process.env)wherecfgisloadConfigFileOnly()merged with the brain's DB-plane provider keys vialoadConfigWithEngine— file plane alone if that read fails — so a--forcere-init sees a Voyage key that lives only in the config table). A recipe with a customresolveAuthneeds no env key (mirrors the gateway); aprovider_base_urlsoverride marks the provider self-hosted.describeRerankerFix(r)renders the paste-ready one-liner (unknown-model > missing key + disable command).src/core/ai/reranker-readiness-engine.tsis the engine-plane wrapper doctor andgbrain search modesshare:rerankerReadinessForEngine(engine, model)reads the LIVE gateway snapshot (env + base_urls — exactly whatrerank()consults, so the verdict cannot disagree with search and a mounted brain's DB plane cannot steer it) and falls back to env > file > DB-plane provider keys +provider_base_urlsvialoadConfigWithEngineonly when no gateway is configured;redactReadinessForRemote(modes-report.ts) stripsrequired_key/key_present/fixfrom thesearch_modesop for untrusted callers.test/ai/reranker-readiness.test.tspins agreement withisAvailable('reranker', m)on an env × model matrix (recipeKnown && hasTouchpoint && keyPresent) so the two predicates cannot drift.src/core/ai/types.ts— provider/recipe types.EmbeddingTouchpointhas optionalchars_per_token(default 4, matching OpenAI tiktoken on English) andsafety_factor(default 0.8, budget-utilization ceiling), both consulted only whenmax_batch_tokensis also set; Voyage declareschars_per_token=1+safety_factor=0.5to handle dense payloads (CJK/JSON/base64). Pre-split budget =max_batch_tokens × safety_factor / chars_per_token.EmbeddingTouchpoint.multimodal_models?: string[]model-level allow-list for recipes mixing text-only + multimodal models under one touchpoint (Voyage's 12 models sharesupports_multimodal: truebut onlyvoyage-multimodal-3accepts/multimodalembeddings); when omitted, recipe-levelsupports_multimodalis sufficient.AIGatewayConfig.embedding_multimodal_model?: stringletsembedMultimodal()route to a different model thanembedding_model(OpenAI text + Voyage images without flipping the primary pipeline).AIGatewayConfig.embedding_image_ocr_model?: stringis its OCR sibling:generateOcrText()routes to it instead of the expansion model; a directprovider:modelstring, nevermodels.tier-resolved.EmbeddingTouchpoint.trust_custom_dims?: true— passthrough tier for a user-declared--embedding-dimensionson local / bring-your-own-backend recipes (ollama, llama-server, litellm) where the model catalog can't be enumerated; consumed byisCustomDimValidForProviderinsrc/core/embedding-dim-check.tsAFTER Tier 1 (recipedims_options) and Tier 2 (provider Matryoshka allowlists), so a recipe that declares fixed options (openrouter) is still governed by those and fixed-dim hosted providers (openai/voyage) stay fail-closed; the provider's/embeddingsresponse-dim validation catches a genuine mismatch pre-storage.Recipe.default_headers?: Record<string, string>(static) andRecipe.resolveDefaultHeaders?(env)(env-templated) seam for per-recipe headers riding alongside auth on every openai-compat touchpoint; mutually exclusive (declaring both throwsAIConfigErrorat gateway-configure time); keys conflicting with the resolved auth header (Authorization, the resolver's custom header) rejected atapplyResolveAuthcall time so defaults can't shadow auth. Used by OpenRouter for theHTTP-Referer+X-OpenRouter-Title+X-Titleattribution triple.