Services

Architecture Section

This page is part of the Architecture section. See also the Dependency Injection page for how services connect to core through behaviour records.

Services are fixed branches the core depends on. Each conforms to the Service shape (core/service.gleam) and does real work: HTTP calls, SQLite queries, shell execution. Services are built-in -- not user-swappable.

Services connect to core through behaviour records (defined in core/behaviours/behaviours.gleam). Each service that core depends on has a companion *_behaviour.gleam constructor that returns a behaviour record. Wiring happens in agent_supervisor.gleam at startup. See the Dependency Injection page for details on the pattern, the wiring chain, and the full table of 13 behaviour records.

Service Catalog

API (api/openai/)

OpenAI-compatible completions client. Handles chat completions with tool use, retries with jittered exponential backoff, truncation continuation, and structured error classification (AuthError, RateLimitError, ServerError, ContextOverflowError).

Storage (storage/)

SQLite persistence layer with 8 modules:

Module	Role
db.gleam	Connection open/close, WAL checkpoint, integrity check, transactions
db_behaviour.gleam	DbConnector behaviour constructor
session_db.gleam	Session CRUD, message append, FTS5 search, pruning, export
session_db_behaviour.gleam	SessionStore behaviour constructor (16 functions)
memory_db.gleam	Memory CRUD with validation, dedup, and scanning; MemoryStore constructor
cron_db.gleam	Cron job persistence; CronStore behaviour constructor
schema.gleam	Database schema creation and migrations
cfg.gleam	Storage config (DB path, WAL settings)

Uses WAL journal mode with automatic fallback for NFS/SMB filesystems. Includes FTS5 full-text search across messages.

Admin (admin/)

Inspection and management interface. Exposed as both REPL slash commands (/sessions, /db, /dnd, /models) and a TCP line-delimited JSON protocol. The daemon listens on a configurable admin port.

Tokens (tokens/)

Heuristic token estimation with CJK-aware counting. Provides context window overflow warnings during conversation. Exposes a token_estimator() constructor returning a TokenEstimator behaviour record.

Guardrails (guardrails/)

Shell command safety layer. Hardline blocks for dangerous commands, dangerous-pattern detection, approval flow, and circuit breaker for stuck tool loops with tool-specific recovery hints. guardrails_behaviour.gleam constructs the Guardrail behaviour record.

Persona (persona/)

Loads persona definition files (SOUL.md, PERSONA.md) that shape the agent's behavior and system prompt.

Context (context/)

System prompt builder. Auto-discovers project files (CLAUDE.md, AGENTS.md, HERMES.md, .cursorrules), injects environment context, tool guidance, and memory. Exposes a context_builder() constructor returning a ContextBuilder behaviour record.

Titler (titler/)

Fire-and-forget LLM title generation. Automatically names new sessions based on the first exchange.

Pulse (pulse/)

Time-driven periodic task execution. Reads tasks from PULSE.md and executes them on a configurable interval (default: every 30 minutes).

Cron (cron/)

Traditional 5-field cron scheduler. Polling loop evaluates cron expressions and executes due jobs (shell commands or agent prompts). Uses CronStore behaviour (via cron_db.gleam) for persistence and core/schedule.gleam for shared cron expression parsing.

Harness (harness/)

Deterministic validation gating for autonomous actions. Safety layer that gates autonomous tool execution behind configurable rules.

Notifications (notifications/)

Notification delivery and Do Not Disturb coordination. Manages DND rules (scheduled quiet hours, indefinite DND) with conflict detection. dnd_behaviour.gleam constructs the DndChecker behaviour record used by the send_message tool.

Logger (logger/)

Structured logging service. Provides 4 log levels (Debug, Info, Warn, Error), 8 categories mirroring the project architecture (App/Core/Services/Plugins/Tools/Gateways/Hooks/Config), and dual output: JSON-lines to a rotating log file + human-readable to stdout. The logger process is registered as agent_logger so any module in any process can call it without threading a reference. logger_behaviour.gleam constructs the Logger behaviour record.

Supervisor (supervisor/)

Service lifecycle coordinator. Starts, monitors, and stops all supervised services. Coordinates with the root supervisor (agent_supervisor.gleam) and the gateway supervisor for full OTP supervision tree coverage.