Services

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

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. Manages session storage, message history, memory entries, and cron jobs. 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.

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.

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.

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 with runtime-managed jobs via agent tools (cron_create, cron_list, cron_update, cron_delete). Jobs persist in SQLite.

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. Powers the telegram/send_message gateway tool.