Configuration

ChatClientConfig

Passed to createChatClient(config). Every field is optional; the SDK falls back to mock/development defaults when omitted.

Minimum viable config

The two configs you'll actually start from:

import { createChatClient, tokenEndpointAuth, createProxyTransport } from 'gecx-chat';
import { createMockTransport } from 'gecx-chat/testing';

// Dev — no credentials, no backend
const devClient = createChatClient({
  transport: createMockTransport(),
});

// Production — your token endpoint + a proxy you control
const prodClient = createChatClient({
  auth: tokenEndpointAuth({ endpoint: '/api/chat-token' }),
  transport: createProxyTransport({ endpoint: '/api/chat' }),
});

Everything below is optional. Add fields as you need them.

Auth

Option	Type	Default	Description
`auth`	`AuthProvider`	Mock provider	Authentication provider. Use `tokenEndpointAuth()`, `customAuth()`, or `googleTokenBrokerAuth()`. Required in production.

Transport

Option	Type	Default	Description
`transport`	`ChatTransport`	Inline echo mock	Transport for sending and streaming messages. Use `createProxyTransport()`, `createSessionApiTransport()`, `createHttpTransport()`, or `createWebSocketTransport()`. Required in production.

Storage

Option	Type	Default	Description
`storage`	`StorageAdapter \| StorageConfig`	`undefined` (no persistence)	Message and session persistence. Pass a `StorageAdapter` directly or a `StorageConfig` object with `mode` and `consent`.

StorageConfig shape:

Field	Type	Values	Description
`mode`	`string`	`'session'`, `'local'`, `'memory'`	`session` uses `sessionStorage`, `local` uses `localStorage`, `memory` is in-memory only.
`consent`	`string`	`'functional'`, `'none'`	`'none'` forces memory-only storage regardless of `mode`.

Tools

Option	Type	Default	Description
`tools`	`ClientTool[]`	`[]`	Client-side tools the agent can invoke. Created with `defineClientTool()`.
`approvalHandler`	`ToolApprovalHandler`	`undefined`	Global approval handler for tool calls requiring user confirmation.

Capabilities

Option	Type	Default	Description
`capabilities`	`Partial<SessionCapabilities>`	See below	Override default session capability flags.

Default SessionCapabilities:

Field	Type	Default
`streaming`	`boolean`	`true`
`richContent`	`boolean`	`true`
`fileUpload`	`boolean`	`true`
`handoff`	`boolean`	`true`
`clientTools`	`boolean`	`true`
`citations`	`boolean`	`true`
`suggestionChips`	`boolean`	`true`
`markdown`	`boolean`	`true`
`a2ui`	`boolean`	`false`
`a2uiProtocolVersions`	`Array<'v0.9'>`	`['v0.9']`
`a2uiCatalogIds`	`string[]`	`[]`
`a2uiDataModelSync`	`string`	`'disabled'`
`parts`	`PartCapabilities`	All core + standard families at v1

Recovery

Option	Type	Default	Description
`recovery`	`Partial<RecoveryPolicy>`	See below	Recovery policy for mid-turn transport disconnects.

Default RecoveryPolicy:

Field	Type	Default	Description
`maxAttempts`	`number`	`5`	Maximum reconnect attempts before giving up.
`initialBackoffMs`	`number`	`500`	First-attempt backoff in milliseconds.
`maxBackoffMs`	`number`	`15000`	Cap on per-attempt backoff after exponential growth.
`jitter`	`string`	`'equal'`	Jitter strategy: `'none'`, `'equal'`, or `'full'`.
`resumeMode`	`string`	`'resume'`	How to rejoin a partially-streamed turn: `'none'`, `'replay'`, or `'resume'`.

Network

Option	Type	Default	Description
`network`	`NetworkMode`	`'auto'` (browser)	`'auto'` queues sends while offline; `'strict'` surfaces `NETWORK_OFFLINE` immediately; `'off'` disables the monitor.
`multiTab`	`MultiTabMode`	`'leader'` (when storage exists)	`'leader'` runs transport in one tab; `'broadcast'` runs per tab; `'off'` disables coordination.

Identity

Option	Type	Default	Description
`identity`	`IdentityConfig`	`undefined`	Identity bootstrap and cross-tab sync options.

IdentityConfig shape:

Field	Type	Default	Description
`initial`	`Partial<ChatIdentity>`	`undefined`	Seed identity fields at construction time.
`syncAcrossTabs`	`boolean`	`true` (when durable storage exists)	Enable BroadcastChannel-based identity sync across tabs.

Governance

Option	Type	Default	Description
`governance`	`DataGovernancePolicy`	Defaults (functional consent, session retention)	Data governance policy: consent, retention, export, audit, and server-ack requirements.

Analytics and Telemetry

Option	Type	Default	Description
`analytics`	`ProductAnalyticsConfig`	`undefined`	Product analytics configuration and sink.
`telemetry`	`SessionTelemetrySink`	`undefined`	Low-level session telemetry sink for observability pipelines.

Memory

Option	Type	Default	Description
`memory`	`MemoryConfig`	`undefined` (memory disabled)	Long-term memory. When omitted, no memory tools register, no interceptor installs, and no extractor runs.

MemoryConfig shape (excerpt — see Memory API reference for the full type):

Field	Type	Default	Description
`adapter`	`MemoryAdapter`	required	`createLocalMemoryAdapter`, `createServerMemoryAdapter`, or `createHybridMemoryAdapter`.
`read.mode`	`'inject' \| 'recall' \| 'hybrid' \| 'off'`	`'inject'`	How saved facts reach the model.
`write.tool`	`boolean`	`true`	Register `memory.save`/`update`/`delete` tools.
`write.extractor`	`'heuristic' \| 'llm' \| ExtractorFn \| false`	`false`	Auto-extract facts from completed turns.

Voice

Option	Type	Default	Description
`voice`	`'auto' \| VoiceConfig`	`undefined` (no voice)	When set, exposes `chat.voice` as a lazy getter. Configuring voice does not request the microphone or open a WebSocket — the provider factory runs only when something first reads `session.voice`. `'auto'` picks a provider by environment (mock in test, web-audio mock in dev, Gemini Live in prod/staging).

Permissions

Option	Type	Default	Description
`permissionProvider`	`PermissionProvider`	Browser provider when `navigator` exists; else noop	Device-permission provider (microphone, camera, screen, geolocation).

client.permissions is always available — defaults to createBrowserPermissionProvider() when navigator exists, otherwise createNoopPermissionProvider().

Signals (sentiment + intent)

Option	Type	Default	Description
`signals`	`SignalsConfig`	`undefined` (signals disabled)	Adapter list and escalation rules.

SignalsConfig shape:

Field	Type	Description
`adapters`	`SignalAdapter[]`	Pluggable classifiers. Ships: `ruleAdapter`, `tfjsToxicityAdapter`, `modelToolAdapter`, `geminiAdapter`, `claudeAdapter`, `openaiAdapter`.
`escalation`	`SignalEscalationRule[]`	Declarative rules. Each rule calls `HandoffController.requestTransfer()` with a stable idempotency key.

Agent graph

Agent graphs compose via createAgentGraphTransport(...) wrapping the host transport — there is no top-level agentGraph config field. See Agent Graph guide.

Governance — capability extensions

Sub-policy	Type	Default	Description
`governance.computerUse`	`ComputerUsePolicy`	`{ enabled: false }`	Computer-use opt-in. `enabled`, `allowlist`, `maxDurationMs`, `maxActionsPerSession`, `highRiskActions`, `killSwitch`. See Computer-use.
`governance.commerce`	`CommerceGovernancePolicy`	`undefined`	Strict-mode commerce governance. Fails closed on PCI/PII (PAN/Luhn, CVV, SSN, email, phone, address, EIN) with `COMMERCE_PII_LEAK`.

Misc

Option	Type	Default	Description
`environment`	`string`	`'development'`	`'production'`, `'staging'`, `'development'`, or `'test'`. Controls validation strictness.
`deployment`	`string`	`undefined`	Deployment identifier passed to the transport.
`preserveRawResponses`	`boolean`	`undefined`	When `true`, raw transport events are stored on each `ChatMessage`.
`retry`	`RetryOptions`	`undefined`	Per-send retry options (separate from recovery policy).
`richContent`	`RichContentRegistry \| RichContentDefinition[]`	Default registry (all core + standard families at v1)	Pre-built rich-content registry or array of definitions to register on top of defaults.

UseChatSessionOptions

Passed to the useChatSession() React hook.

Option	Type	Default	Description
`client`	`ChatClient`	`undefined`	Pre-built client instance. Takes priority over `config` and context.
`config`	`ChatClientConfig`	`undefined`	Config for an internally-created client. Ignored if `client` is provided.
`autoStart`	`boolean`	`true`	Automatically create and start a session on mount.
`onMessage`	`(message: ChatMessage) => void`	`undefined`	Callback fired on every new message.
`onError`	`(error: Error) => void`	`undefined`	Callback fired on session errors.
`onStatusChange`	`(status: SessionStatus) => void`	`undefined`	Callback fired on session status transitions.
`onProductAnalyticsEvent`	`(event: ProductAnalyticsEvent) => void`	`undefined`	Callback fired on product analytics events.

Source: docs/reference/configuration.md