Skip to content
View as .md

Configs

Configs hold behaviour that can vary by house or thread, such as bot reply modes, model defaults, prompt overrides, and feature flags. Add a config key rather than a new column or table when a setting follows this scope hierarchy.

DEFAULT_CONFIG (app, in code)
  └─ house patch
       └─ thread patch
            └─ per-agent dispatch override

llm.model picks a reply turn’s model, most specific scope first: a bot’s own model wins, then a thread’s row override, then the resolved config (a thread patch over the house’s), then DEFAULT_BOT_MODEL. llm.systemPrompt is shared instructions: the house’s and the thread’s both reach the bot, house first, between the Arbe guide and the bot’s own persona.

Resolution deep-merges the applicable layers from broadest to narrowest. It returns both the final ResolvedConfig and the chain of patches that produced it, so callers can explain where a value came from. Arrays replace rather than merge.

ConfigPatch describes stored input, so every field is optional. ResolvedConfig describes what callers receive after defaults are applied, so baseline fields are present and non-null. App defaults are not stored in the database; DEFAULT_CONFIG is their source of truth.

Per-agent dispatch settings live under dispatch.perAgent[agentId]. Agents are shared across houses, so they are an override within the house/thread chain rather than another scope. botTurnLimit (default 3, any whole number) rides the same per-agent patch: consecutive bot turns before that bot rests. Zero disables the limit. The scope-wide dispatch.settledBotTurnThreshold (default 8, range 0–20) stops an exchange after that many consecutive short closing bot replies; zero disables it.

Gotchas

  • Omitted and null mean different things. Omit or unset a key to inherit from the next broader scope. Store null to ignore ancestor overrides and reset that key to DEFAULT_CONFIG.
  • Adding a required resolved key can make a newer client reject responses from an older server. Deploy the server first, or give the resolved schema a temporary default when deployment order is not guaranteed.

The director’s own model and thinking level are process settings, not config; see backstage settings.

Code: @arbe/core/schemas/config.ts owns schemas, defaults, and merge semantics. @arbe/core/configs.ts owns resolution and writes. The common per-agent entry point is documented under agent trigger modes.