All operational defaults in AgentSessionManager are managed through AgentSessionManager.Config. This module provides a single source of truth for every timeout, limit, buffer size, and tuning parameter used throughout the library.
How Configuration Works
Every call to AgentSessionManager.Config.get/1 resolves a value through three layers, in priority order:
- Process-local override - set via
AgentSessionManager.Config.put/2, scoped to the calling process. Automatically cleaned up when the process exits. - Application environment - set via
config :agent_session_manager, key: value or Application.put_env/3. - Built-in default - hardcoded fallback.
Config.get(:command_timeout_ms)
|
|-- Process dictionary has override? --> return override
|-- Application.get_env has value? --> return app env value
|-- Return built-in default (30_000)
This layering follows the same pattern as Elixir's Logger for per-process log levels and enables fully concurrent (async: true) testing.
Application Config Example
Override any default in config/config.exs or config/runtime.exs:
# config/config.exs
config :agent_session_manager,
command_timeout_ms: 60_000,
max_parallel_sessions: 200,
event_buffer_size: 5_000
Process-Local Overrides (for Testing)
# In a test - only affects the current process
AgentSessionManager.Config.put(:command_timeout_ms, 1_000)
assert AgentSessionManager.Config.get(:command_timeout_ms) == 1_000
# Remove override (falls back to app env / default)
AgentSessionManager.Config.delete(:command_timeout_ms)
Complete Key Reference
Feature Flags
| Key | Type | Default | Description |
|---|
:telemetry_enabled | boolean | true | Enable/disable telemetry event emission |
:audit_logging_enabled | boolean | true | Enable/disable audit logging |
Timeouts
All timeout values are in milliseconds.
| Key | Default | Description |
|---|
:stream_idle_timeout_ms | 120_000 | StreamSession idle timeout before auto-close |
:task_shutdown_timeout_ms | 5_000 | StreamSession task shutdown grace period |
:await_run_timeout_ms | 60_000 | SessionServer timeout for awaiting run completion |
:drain_timeout_buffer_ms | 1_000 | Extra buffer added to SessionServer drain timeout |
:command_timeout_ms | 30_000 | Shell command execution timeout (Exec + ShellAdapter) |
:execute_timeout_ms | 60_000 | ProviderAdapter execute call timeout |
:execute_grace_timeout_ms | 5_000 | Grace period added on top of execute timeout |
:circuit_breaker_cooldown_ms | 30_000 | Circuit breaker open-to-half-open cooldown |
:sticky_session_ttl_ms | 300_000 | Sticky session routing TTL |
:event_stream_poll_interval_ms | 250 | Poll interval when no new events in stream |
:genserver_call_timeout_ms | 5_000 | Default GenServer.call timeout for store/adapter dispatch |
Buffer and Memory Limits
| Key | Default | Description |
|---|
:event_buffer_size | 1_000 | Max events held in-memory in EventStream |
:max_output_bytes | 1_048_576 | Max captured shell command output (1 MB) |
:max_patch_bytes | 1_048_576 | Max git diff patch size (1 MB) |
:error_text_max_bytes | 16_384 | Max bytes retained in provider_error.stderr before emission/persistence |
:error_text_max_lines | 200 | Max lines retained in provider_error.stderr before emission/persistence |
Concurrency
| Key | Default | Description |
|---|
:max_parallel_sessions | 100 | ConcurrencyLimiter max parallel sessions |
:max_parallel_runs | 50 | ConcurrencyLimiter max parallel runs globally |
:max_queued_runs | 100 | Max queued runs per SessionServer / RunQueue |
Circuit Breaker
| Key | Default | Description |
|---|
:circuit_breaker_failure_threshold | 5 | Consecutive failures before circuit opens |
:circuit_breaker_half_open_max_probes | 1 | Max probe requests in half-open state |
SQLite
| Key | Default | Description |
|---|
:sqlite_max_bind_params | 32_766 | SQLite bind parameter hard limit per query |
:sqlite_busy_retry_attempts | 25 | Retry attempts for "database is locked" errors |
:sqlite_busy_retry_sleep_ms | 10 | Sleep between busy retries |
Query Limits
| Key | Default | Description |
|---|
:max_query_limit | 1_000 | Absolute max rows per query (EctoQueryAPI) |
:default_session_query_limit | 50 | Default session search result limit |
:default_run_query_limit | 50 | Default run search result limit |
:default_event_query_limit | 100 | Default event search result limit |
Retention Policy
These defaults are used by RetentionPolicy.new/0. Per-policy overrides are still supported by passing keyword options to RetentionPolicy.new/1.
| Key | Default | Description |
|---|
:retention_max_completed_age_days | 90 | Days before completed sessions are pruned |
:retention_hard_delete_after_days | 30 | Days before hard delete |
:retention_batch_size | 100 | Batch size for prune operations |
:retention_exempt_statuses | [:active, :paused] | Statuses exempt from pruning |
:retention_exempt_tags | ["pinned"] | Tags that exempt sessions from pruning |
:retention_prune_event_types_first | [:message_streamed, :token_usage_updated] | Event types pruned first |
Cost
| Key | Default | Description |
|---|
:chars_per_token | 4 | Approximate characters per token for estimation |
PubSub integration is configured per use via sink/callback options (prefix, scope, message_wrapper), not via AgentSessionManager.Config keys.
Shell Adapter
| Key | Default | Description |
|---|
:default_shell | "/bin/sh" | Default shell binary |
:default_success_exit_codes | [0] | Exit codes considered success |
Workspace
| Key | Default | Description |
|---|
:excluded_workspace_roots | [".git", "deps", "_build", "node_modules"] | Directories excluded from workspace hashing |
Routing
| Key | Default | Description |
|---|
:default_router_name | "router" | Default ProviderRouter instance name |
Environment-Specific Configuration
# config/dev.exs - relaxed timeouts for development
config :agent_session_manager,
command_timeout_ms: 120_000,
await_run_timeout_ms: 300_000
# config/test.exs - fast timeouts for testing
config :agent_session_manager,
command_timeout_ms: 5_000,
await_run_timeout_ms: 10_000,
event_stream_poll_interval_ms: 10
# config/prod.exs - tuned for production
config :agent_session_manager,
max_parallel_sessions: 500,
max_parallel_runs: 200,
max_queued_runs: 1_000,
event_buffer_size: 10_000,
sqlite_busy_retry_attempts: 50,
retention_max_completed_age_days: 365
Programmatic Access
# Get the built-in default (ignores overrides)
AgentSessionManager.Config.default(:command_timeout_ms)
#=> 30_000
# Get the resolved value (checks process → app env → default)
AgentSessionManager.Config.get(:command_timeout_ms)
#=> 30_000
# List all valid configuration keys
AgentSessionManager.Config.valid_keys()
#=> [:telemetry_enabled, :audit_logging_enabled, :stream_idle_timeout_ms, ...]