Skald-Circle/docs/architecture.md

Architecture

Two-Layer Design

src/
  core/         ← headless application core (no HTTP, no Axum)
    skald/      ← Skald: Runtime context + 8 domain bundles; staged new() / shutdown()
      mod.rs        ← Skald struct (aggregate) + new() composition root + shutdown()
      runtime.rs    ← Runtime: cross-cutting context (db, buses, global_tx, shutdown, supervisor)
      bundles.rs    ← 8 domain bundles + their build() functions
      wiring.rs     ← wire() (OnceLock cycle-breakers) + spawn_background()
      supervisor.rs ← TaskSupervisor: named background-task handles, joined on shutdown
      accessors.rs  ← impl Skald: one accessor per manager (the logical API surface)
    …           ← all domain modules (db, llm, session, cron, plugin, …)
  frontend/     ← web presentation layer
    mod.rs      ← WebFrontend: wires router_factory, starts plugins, runs Axum
    server.rs   ← WebServer (Axum router, TcpListener)
    api/        ← 18 HTTP + WebSocket handlers — State<Arc<Skald>>
  core/config.rs    ← CoreConfig + DbConfig, LlmConfig, TicConfig, … (core-owned types)
  frontend/config.rs ← FrontendConfig + ServerConfig, WebConfig
  config.rs         ← Config (YAML parse only) + into_split()
  main.rs           ← thin: tracing → Config → into_split → plugins → Skald::new → WebFrontend::start → shutdown

Skald knows nothing about Axum or HTTP. It can be started headlessly. WebFrontend is the only component that imports Axum and constructs an HTTP server. Skald is no longer a God Object: its ~30 managers are grouped into a cross-cutting Runtime context plus eight cohesive domain bundles, and every consumer (frontend handlers, plugin context) reaches a manager through an accessor method (skald.chat_hub(), skald.db(), …) — never a public field. That accessor surface is the logical boundary a future skald-core crate would keep.

Config::into_split() produces a CoreConfig (db, llm, tic, cron, timezone) for Skald::new() and a FrontendConfig (server, web, timezone) for WebFrontend::new(). The YAML file structure is unchanged. timezone is cloned into both since it is used by the cron scheduler (core) and optionally by the frontend.

Plugin instances are constructed in main.rs as Vec<Arc<dyn Plugin>> and injected into Skald::new() — the core never depends on concrete plugin crates.

---

Component Map

Struct	Created by	Held as	Depends on
SqlitePool	db::init_pool()	Arc<SqlitePool>	—
LlmManager	LlmManager::new()	Arc<LlmManager>	SqlitePool
McpManager	McpManager::new()	Arc<McpManager>	SqlitePool
TaskManager	TaskManager::new()	Arc<TaskManager>	SqlitePool, ChatSessionManager (via OnceLock), ChatHub (via OnceLock)
ToolRegistry	Tools::build()	Arc<ToolRegistry>	McpManager, TaskManager, PluginManager, SecretsStore
ApprovalManager	Interaction::build()	Arc<ApprovalManager>	SqlitePool
ClarificationManager	Interaction::build()	Arc<ClarificationManager>	—
Inbox	Interaction::build()	(owned by Interaction bundle)	ApprovalManager, ClarificationManager, ElicitationManager, ToolRegistry
ToolCatalog	Tools::build()	(owned by Tools bundle)	ToolRegistry, McpManager
ChatEventBus	Runtime::bootstrap()	Arc<ChatEventBus>	—
ContextCompactor	Conversation::build() (when llm.compaction configured)	Option<Arc<ContextCompactor>> (consumed by ChatSessionManager)	LlmManager, ChatEventBus
ChatSessionManager	ChatSessionManager::new()	Arc<ChatSessionManager>	SqlitePool, LlmManager, ToolRegistry, McpManager, ApprovalManager, ClarificationManager, ChatEventBus, ContextCompactor
ChatHub	ChatHub::new()	Arc<ChatHub>	SqlitePool, ChatSessionManager, ApprovalManager
TicManager	TicManager::new()	Arc<TicManager>	SqlitePool, ChatHub, ChatSessionManager
Skald	Skald::new(&core_cfg, plugins)	Arc<Skald>	all of the above
WebFrontend	WebFrontend::new(skald, &frontend_cfg)	owned by main	Arc<Skald>, FrontendConfig

Circular Dependencies

The construction cycles cannot be expressed as a nested value tree, so the managers break them with std::sync::OnceLock (or RwLock<Option<_>>) setters. All of these setters are called in one place — the wire() function in skald/wiring.rs — run after every bundle is built and before background tasks start. Bundle structs therefore never hold references to each other; the only cross-bundle links live in the managers' OnceLocks.

TaskManager ↔ ChatSessionManager: TaskManager needs ChatSessionManager to dispatch jobs, but ChatSessionManager is built after ToolRegistry which holds Arc<TaskManager>. TaskManager is created first (in Tasks::build), set_session() is called in wire() once ChatSessionManager exists.

TaskManager ↔ ChatHub: Same pattern — set_hub() is called in wire(). The cron tick loop starts 30 s after start(), so the hub is always ready by the first real job dispatch.

McpManager ↔ ElicitationManager: set_elicitation_handler() is called in wire(); MCP initialize() is only spawned afterwards (in spawn_background()), so stdio servers start with a handler for server-initiated elicitation/create.

PluginManager ↔ Skald: the one Arc<Skald> back-reference. PluginManager is constructed early (in Integrations::build, so tools can register), then set_skald(Arc<Skald>) is called as the very last step of new(), after Arc::new(Skald { … }). set_router_factory(RouterFactory) is called by WebFrontend::start() before start_enabled().

---

Startup Sequence

main.rs

1. Init tracing (tracing-appender daily rolling to logs/)
2. Config::load() → config.into_split() → (CoreConfig, FrontendConfig)
3. Build Vec<Arc<dyn Plugin>> — all plugin instances constructed here
4. Skald::new(&core_cfg, plugins) — see sequence below
5. WebFrontend::new(skald, &frontend_cfg) + .start() — see sequence below
6. Await ctrl_c
7. skald.shutdown() + handle.shutdown()

Inside Skald::new(&core_cfg, plugins)

new() is a staged composition root: it builds the Runtime context, then each domain bundle in dependency order via its own Bundle::build(...), then resolves cycles and starts background tasks. (db::init_pool() runs earlier, in main.rs, and the pool is passed in.)

1. agents::discover() — scans agents/*/ for meta.json + AGENT.md (logged only)
2. Runtime::bootstrap(pool) — GlobalConfigManager, SystemEventBus, ChatEventBus, the GlobalEvent broadcast channel (global_tx), CancellationToken, TaskSupervisor
3. Models::build — ProviderRegistry (+6 built-in providers), LlmManager, SecretsStore, MemoryManager
4. Media::build — ImageGeneratorManager, TranscribeManager, TtsManager
5. Integrations::build — McpManager (NOT yet initialized), PluginManager (plugins registered, not started)
6. Tasks::build — TaskManager (scheduler, not started), ProjectManager, ProjectTicketManager — before Tools so cron tools can capture cron
7. Tools::build — ToolRegistry (all built-in tools, capturing mcp/plugins/cron/secrets + mobile-connector tools), ToolCatalog, LlmCommandManager
8. Interaction::build — ApprovalManager (+ 4 non-fatal seed_*), ClarificationManager, ElicitationManager, Inbox
9. Conversation::build — RunContextManager (+ seed), ContextCompactor (if configured), ChatSessionManager, ChatHub (+ register("web"/"talk")), TicManager
10. Infra::build — LatexCompiler, LocationManager, remote slot (None)
11. wire(...) — all OnceLock cycle-breakers in one place (cron.set_session/set_hub/set_self_arc, ticket.set_task_manager, chat_hub.set_task_mgr, mcp.set_elicitation_handler)
12. spawn_background(...) — every long-lived task, each registered by name with the supervisor: llm-log-cleanup, session-cancel, mcp-init (mcp.initialize()), cron, ticket-listener, tic
13. Arc::new(Skald { rt, models, media, tools, integrations, tasks, conversation, interaction, infra })
14. skald.plugin_manager().set_skald(Arc::clone(&skald)) — the one Arc<Skald> back-reference, last

Inside WebFrontend::start()

28. plugin_manager.set_router_factory(factory) — provides Axum router factory to plugins
29. plugin_manager.set_web_port(port) — provides HTTP port to plugins (e.g. Tailscale)
30. plugin_manager.start_enabled() — starts Telegram and other enabled plugins
31. plugin_manager.start_config_watcher(shutdown_token) — polls DB every 30 s
32. WebServer::start(addr) — Axum HTTP+WS server begins listening

---

Request Lifecycle

1. Client opens WebSocket: GET /api/ws
2. handle_socket() gets or creates ChatSessionHandler via ChatHub::session_handler("web")
3. Client sends ClientMessage JSON over WS
4. ChatHub::send_message("web", prompt, opts) enqueues the message on the source's inbox and returns; it does not run the turn inline (see Per-source inbox in session.md)
5. The source's single consumer task drains the inbox, coalescing any messages that piled up during an in-flight turn into one prompt (joined by blank lines), and calls handler.handle_message(...)
6. handle_message acquires processing: Mutex<()> (one at a time per session)
7. run_agent_turn is a thin round orchestrator (up to max_tool_rounds rounds) that delegates each step to focused collaborators (see session.md):
   • Build context: build_openai_messages() → system prompt + history + tool results
   • Apply permission-group visibility filter (hide tools Denyd for the session's run-context group)
   • call_llm_round() — one LLM call + automatic model fallback on retriable errors
   • LlmTurn::Message → send Done event, exit loop
   • LlmTurn::ToolCalls → for each call, handle_tool_call():
     • effective_args() (working-dir injection) → run_approval_gate() → optional PendingWrite, wait for user
     • execute_tool_call() → send ToolStart; call_agent recurses via dispatch_sub_agent
     • record_tool_outcome() → send ToolDone / ToolError / ToolCancelled
   • All events are emitted through the TurnEmitter seam (emitter.rs)
8. Main loop sends Done event with final content and token counts

---

Notification Flow (background)

MCP server stdout (JSON-RPC notification, no id field)
  → McpServer reader loop (src/core/mcp/server.rs)
  → notification_tx (mpsc::UnboundedSender)
  → McpManager::notification_consumer
  → db::mcp_events::insert(source, method, payload)

[every tic.interval_secs (default 900 s) — TicManager::run_tick()]
  → mcp_events::pending_limited(tic.batch_size)
  → mcp_events::mark_processed(ids)
  → build_prompt(events)
  → ChatHub::send_message("tic", prompt)   ← ephemeral session
  → TIC agent runs, calls notify(briefing)
  → ChatHub::notify_sync → mpsc channel

[ChatHub::notification_consumer]
  → batching window (200 ms)
  → appends synthetic Assistant message to chat_history (reasoning_content + is_synthetic=true)
  → inserts chat_llm_tools row for read_notification (status='done', result=[briefings])
  → calls hub.resume(home_source)
  → resume_turn picks up the synthetic tool call, runs the LLM loop
  → user sees assistant briefing in home conversation

---

Skald Fields (bundle model)

Skald holds one cross-cutting Runtime context plus eight domain bundles — all private. Consumers reach managers through accessor methods named after the manager (skald.chat_hub(), skald.db(), skald.approval(), …), defined in skald/accessors.rs. The frontend uses these via State<Arc<Skald>>; the plugin context (PluginManager::build_context) uses the same surface. High-level facets like Inbox and ToolCatalog encapsulate several underlying managers behind a simpler API.

Bundle	Field	Members (accessor → manager)
Runtime	rt	db → SqlitePool, config → GlobalConfigManager, config_properties, system_bus → SystemEventBus, event_bus → ChatEventBus, global_tx (GlobalEvent sender), shutdown_token, supervisor → TaskSupervisor
Models	models	provider_registry, llm_manager, secrets, memory_manager
Media	media	image_generator_manager, transcribe_manager, tts_manager
Tools	tools	tools → ToolRegistry, catalog → ToolCatalog, command_manager → LlmCommandManager
Integrations	integrations	mcp → McpManager, plugin_manager → PluginManager
Tasks	tasks	cron → TaskManager, projects → ProjectManager, ticket_manager → ProjectTicketManager
Conversation	conversation	manager → ChatSessionManager, chat_hub → ChatHub, run_context_manager → RunContextManager, tic_manager → TicManager
Interaction	interaction	approval → ApprovalManager, inbox → Inbox, clarification → ClarificationManager, elicitation → ElicitationManager
Infra	infra	latex_compiler → LatexCompiler, location_manager → LocationManager, remote → Arc<RwLock<Option<Arc<dyn RemoteAccess>>>>

TicManager lives in Conversation (not Tasks) because it is constructed from and drives the conversation stack (session manager + chat hub + run context); this keeps every bundle a single-shot build() with no two-phase init.

---

Graceful Shutdown

On SIGINT, main.rs executes:

1. skald.shutdown():
   • rt.shutdown_token.cancel() — signals all background loops to exit their select!
   • rt.supervisor.join_all(10 s) — awaits every supervised task against a shared deadline, logging any laggard by name
   • plugin_manager.stop_all()
2. handle.shutdown() — drains and closes the Axum HTTP server

Tasks registered with the TaskSupervisor (spawned in spawn_background, joined on shutdown, listed by their supervisor name):

Supervisor name	Source
cron	src/core/cron/mod.rs (TaskManager::start)
ticket-listener	src/core/projects/tickets.rs
tic	src/core/tic/mod.rs
session-cancel	src/core/skald/wiring.rs
mcp-init	src/core/skald/wiring.rs → McpManager::initialize
llm-log-cleanup	src/core/db/llm_requests/cleanup.rs

Other tasks are spawned inside their managers and honor shutdown_token.cancelled() but are not (yet) registered with the supervisor — cancellation stops them, but they are not individually joined: PluginManager config watcher (src/core/plugin/mod.rs), McpManager notification consumer (src/core/mcp/mod.rs), ChatHub notification consumer (src/core/chat_hub/mod.rs), TtsManager/TranscribeManager reload watchers (src/core/{tts,transcribe}/manager.rs).

---

Workspace Crates

The binary depends on several independent library crates in crates/. Each crate has no dependency on the main skald crate and can be published or reused standalone.

Crate	Path	Purpose
core-api	crates/core-api/	Shared types and traits: ServerEvent, GlobalEvent, InterfaceTool, SendMessageOptions, ChatHubApi trait
llm-client	crates/llm-client/	LLM client abstraction (OpenAI-compat, Anthropic, Ollama)
mcp-client	crates/mcp-client/	MCP client (JSON-RPC over stdio/SSE)
honcho-client	crates/honcho-client/	Honcho long-term memory HTTP client

core-api — plugin extraction boundary

core-api is the designated contract crate for plugin independence. A plugin that depends only on core-api (instead of the full main crate) can be extracted into its own workspace member without circular dependencies.

See crates/workspace.md for the full extraction roadmap.

Future: skald-core crate

src/core/ is designed as a stepping stone toward extracting the headless core into a standalone crates/skald-core/ crate. The accessor facade in skald/accessors.rs is the seam: the frontend and plugin context already consume Skald only through those methods, never its fields. When the extraction happens:

• src/core/ moves to crates/skald-core/src/
• the skald/accessors.rs methods are promoted to a pub trait SkaldApi (they already have that shape)
• the two raw-SQL leaks the frontend still has (skald.db() used directly for a handful of sqlx::query* calls in sessions.rs/dev.rs/stats.rs, and skald.system_bus() for two .send() sites) must be closed behind repository/intent methods first
• src/frontend/ depends on skald-core as a path dependency

---

When to Update This File

• A new manager is added to a Skald bundle (add its accessor + update the bundle table)
• A bundle is added, removed, or a manager moves between bundles
• The staged construction in Skald::new() / a Bundle::build() or WebFrontend::start() changes
• The request lifecycle changes (new event type, new loop behavior)
• A new circular dependency and its wire() resolution is introduced
• A background task is added to (or removed from) the TaskSupervisor
• A new workspace crate is added